handrews
commented
2 months ago 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.
From @DavidBiesack in OAI/OpenAPI-Specification#239:
I would prefer link schemes based on
operationIdrather 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
operationIdofupdateThinggets an HTML anchor name-code-updatething--code-, and a schemamyThinggets the anchortocsmything(i.e. prefixtocs... 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
summaryor the schema'stitle[Title](operation:updateThing)[][operation:updateThing)-- uses the operationsummaryfor the link title, or theoperationIdif none, else the HTTP verb and path.[Title](schema:schemaName)[](schema:schemaName)-- uses the schema'stitlefor the link title, or the schema name if none[Title](schema:schemaName.propertyName)[](schema:schemaName.propertyName)- title isschemaName.propertyName(the property'stitle, 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 . Thejsonref:notation may work for these cases.TBD: references to elements in external OpenAPI documents...