Allow references between operations inside descriptions.

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].",

[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…

[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'