operationId as a plain name fragment

[handrews]

From @DavidBiesack in OAI/OpenAPI-Specification#239:

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...

[handrews]

Having thought on this more, I don't think operationId can easily be used as a fragment. Fragments are scoped to resources, while operationId is scoped to the entire API description, which can be spread across multiple resources.

Even if we declare that operationId is scoped to resources when used as a fragment, in addition to being confusingly different from its behavior in the Link Object (and likely elsewhere), the field does not impose any syntax restrictions at all, meaning that it could collide with other fragment syntaxes such as JSON Pointer. We really do not want ambiguous fragment syntaxes.

@DavidBiesack while I think you have some good use cases here, I don't see a way to make this work as things currently stand. However, all sorts of referencing and identification changes are being considered for OAS 4 (Moonwalk) at the OAI/sig-moonwalk repository, and it might be worth bringing this up there.