Allow references between operations inside descriptions.

[ryangyoung]

For documentation purposes, it would be wonderful if we could add href-type links in Swagger annotations. The purpose of these links would be to reference one API call from another for documentation completeness (not for documenting the flow, per se). Similar to the "transfers API" link here: https://stripe.com/docs/api#balance_object

In the annotations, it would be something like:

    @Timed
    @ApiOperation(value = "Request an access token",
            notes = "This method exchanges the code returned in the [link to Auth resource].",

[webron]

@ryangyoung - following our discussion in the google group, thanks for opening this issue.

I'm changing the title of the issue since it refers to swagger-core specifically, and we may need/want to address this in the spec itself (which is why the issue is here and not on swagger-core).

The idea is to add support for hyperlinking between operations within the description, to allow for references (not flow).

This may mandate the operationId becoming mandatory again, or otherwise, require it if hyperlinking is used. Of course, other suggestions would be appreciated.

[ekampp]

It seems most likely that people who are using hyperlinking already implements the operationId. And I don't see a hinderance to listening the the hash change in the url, and opening the matching operation when it changes?

[MattSANU]

I would also like to generate links to related URLs/resources solely from the part of the Swagger specification that describes the URL currently being accessed. I think the OP here and I share an intention to use Swagger and HATEOAS to create a truly RESTful API.

However rather than decorating paths and/or operations in the way that this issue proposes, I would prefer to permit an optional additional 'links' object inside paths and/or operations. See #440 for details.

[MattSANU]

Just to be clear, I am not using Swagger to document an existing API - I'm using it to actually implement the API. I have Python WSGI middleware and applications which configure themselves according to a Swagger specification they load at runtime. This works well so far, but if I want my web service to be RESTful, in responses, I need to include links to other possibly-interesting URLs (so-called HATEOAS). To accomplish this, I either need to hard-code links into the application's responses (ugh), maintain information in an additional DSL outside Swagger which inter-relates the Swagger paths and operations (and keep the two DSL files in sync somehow, not fun), or (my preferred option) somehow teach Swagger to understand that paths and operations can have relationships to other paths and operations.

[fehguy]

parent issue #586

[KiaraGrouwstra]

I thought descriptions supported GFM syntax? Because that could do hyperlinks at least. Maybe less powerful than you intended here, but it's something.

[MikeRalphson]

I thought descriptions supported GFM syntax? Because that could do hyperlinks at least. Maybe less powerful than you intended here, but it's something.

@tycho01 description properties support commonMark syntax in OAS 3.0.x, so simple absolute or relative HTTP(S) links will work, the difficulty is in generalising a link to an operation (or other part of the document). Perhaps it would be possible to use a uri scheme such as jsonref:// and/or operationId:// which tooling could rewrite to interpret the link in context.

description: 'This method exchanges the code returned in the [Auth](jsonref://#/paths/~1auth/get) resource'

[godspell2014]

Does anyone have any updates on this issue, has it been resolved?

[gursahibsahni]

I thought descriptions supported GFM syntax? Because that could do hyperlinks at least. Maybe less powerful than you intended here, but it's something.

@tycho01 description properties support commonMark syntax in OAS 3.0.x, so simple absolute or relative HTTP(S) links will work, the difficulty is in generalising a link to an operation (or other part of the document). Perhaps it would be possible to use a uri scheme such as jsonref:// and/or operationId:// which tooling could rewrite to interpret the link in context.

description: 'This method exchanges the code returned in the [Auth](jsonref://#/paths/~1auth/get) resource'

does this work for anyone?

[DavidBiesack]

I would prefer link schemes based on operationId rather than paths, which I find awkward and also a bit fragile when an API is in early stages.

Admittedly, supporting references from descriptions (technically, from any text element that supports Markdown) does require tools to process those, i.e. preprocess before handing off to the Markdown -> HTML (or other) rendering. For example, we use shins/widdershins to generate HTML API documents; an operation with operationId of updateThing gets an HTML anchor name -code-updatething--code-, and a schema myThing gets the anchor tocsmything(i.e. prefix tocs ... for Table of Contents, Schema?). In both cases, [widder]shins converts the IDs to lowercase. (We purposefully avoid defining elements with the same spelling but different case.)

Note that we need to support references not just to operations as well as anything in components - most notably, schemas, although all components should be supported.

Some possible link notations:

My preference would be to make the title optional, as I don't want to have to copy/paste the operation's summary or the schema's title

• [Title](operation:updateThing)
• [][operation:updateThing) -- uses the operation summary for the link title, or the operationId if none, else the HTTP verb and path.
• [Title](schema:schemaName)
• [](schema:schemaName) -- uses the schema's title for the link title, or the schema name if none
• [Title](schema:schemaName.propertyName)
• [](schema:schemaName.propertyName) - title is schemaName.propertyName (the property's title, if it exists, may not be unique-multiple schemas can have properties with the same title). Allows nesting: thing.fieldA.fieldB.fieldC
• [Title](parameter:parameterName)

Those are the most important to me.

[widder]shins or swagger-ui / swagger-editor or other tools would translate those references into whatever anchor generation scheme they use, as well as attaching unique anchor tags to each element (hopefully in a uniform, predictable manner).

Certainly with schemas, one may want to reference a named parameter within an operation (instead of in components/parameters), or other things not covered above, so this simple notation breaks down, but I think those are referenced much less frequently . The jsonref: notation may work for these cases.

TBD: references to elements in external OpenAPI documents...

[restjohn]

Markdown links could use the fragment delimiter (#) as in $ref syntax to distinguish between references in the same document and external documents. For example, #operations:updateThing vs. things/openapi.yaml#operations:updateThing. The absence of the leading slash from the fragment implies the link is an OpenAPI element ID reference as opposed to a JSON Pointer to an element path, as JSON Reference defines.

[DavidBiesack]

One issue with using Markdown anchors is that there is no standard anchor pattern across all the possible tools that render (HTML or other) API doc. slate, redoc, swagger-ui, shins etc all appear to do it differently. So what works for one tool won't work if you use a different tools, unless all tools that generate HTML generate anchors the same way.
I would like to see some work on this now that 3.1 is (mostly) complete - maybe address in 3.2?

[DavidBiesack]

@webron just bumping this one for visibility -it's a few years old, but seems doable. Details on my April 2019 reply.

[mjpieters]

One issue with using Markdown anchors is that there is no standard anchor pattern across all the possible tools that render (HTML or other) API doc.

That's up to the renderer to worry about, though. A browser-based renderer would simply hook into the hashchange event to then direct the scroll position to the matching operation when a supported prefix is found.

You'd need to support both operation ids and operation refs, e.g. #operationId:<operationId> and #operationRef:#/paths/<encodedPath>/<operationName> (with possibly the #/paths/ part implied), because operations do not have to have an operation ID.

[kephas]

I would prefer link schemes based on operationId rather than paths, which I find awkward and also a bit fragile when an API is in early stages.

This is why REST includes HATEOAS: to decouple the implementation of the server (the paths) from the client. With this, OAS could finally be used to describe REST APIs.

[handrews]

Closing as the two main concerns are now tracked elsewhere. See:

• Specify how relative URLs in rich text descriptions should be resolved #1701 for considerations about relative links in CommonMark description fields
• operationId as a plain name fragment ietf-wg-httpapi/mediatypes#111 for discussing operationId as a plain name fragment in the media type registration