Proposed: Add oasdoc notation for linking to API elements

[DavidBiesack]

Proposal: oasdoc

Several programming languages support documentation annotations which
make it convenient to author more comprehensive documentation by
allowing hyperlinks bewteen language elements.

• Java has javadoc
• Javascript has jsdoc.

I propose OAS devise conventions for embedded documentation links in the
OpenAPI source, so that tools (such as API doc rendering tools) can
support well-known documentation anchors for OAS elements such as operations
and schemas, and that description strings in OAS elements and
external web pages can add links to those elements in a manner that is
agnostic to the tool vendor.

Justification

By adding oasdoc as an extension or convention of the OpenAPI
Specification, API authors can use a tool-agnostic way to ennhance API
documentation, so developers can render the API doc consistently across
different OAS-compliant tools.

Downstream API consumers should be able to download an
OpenAPI description from an API vendor's developer portal or open source
repository and render API documentation with the tool of their choice.

For example, it is useful to provide a summary of an APIs capabilities
in the info.description Markdown text, and link to the important API
operations. Some vendors may create anchors for each operationId but
there is no standard or convention.

For example, given the
The Train Travel API
from bump.sh :

paths:
  /stations:
    get:
      summary: Get a list of train stations
      description: Returns a paginated and searchable list of all train stations.
      operationId: get-stations

Adding infdormational links to the
the top-level info.description makes it easier to highlight
the important operations in the API:

* To fetch a list of train stations, use the {@op list-stations} operation.
* To fetch a list of reserved train trips, use the {@op list-trips} operation.
* ... and so on

API Documentation Vendor Differences

bump.sh

bump.sh generates a URL for each operation.

which does not even yield an anchor; it yields a unique URL such as

https://bump.sh/bump-examples/doc/train-travel-api/operation/operation-get-stations

Redocly

ReDocly creates an anchor for the operation by concatenating:

• the fixed string "tag/"
• a sluggified name from the operation's tags
• the fixed string "/operation/"
• the operationId if one exists (else some other heuristic...)

which would yields the anchor #/tag/Stations/operations/get-stations

Such vendor differences are an inhibitor to writing useful documentation.
By establishing a common (standard) notation, it's more likely API authors
will add links and API navigation aids, increasing the utility of the API doc.

I propose the oasdoc notation, which authors can use to enhance
API documentation and which tool vendors can treat as
a preprocessor to convert agostic links to vendor-specific links.

The API doc vendors may or may not create anchors for schemas or other OpenAPI elements.
For example, bump.sh does not provide anchors for reuest or response schemas;
see The Train Travel API.
However, the API doc tooling vendors can transform the Markdown notation
into navigation links as per their implementation. For example, examining the source
from the bump.sh Train travel API, the left hand navigation contains HTML:

<li class="navigation__operation">
  <a class="navigation__operation-link active"
       data-menu-parent="endpoint-stations"
        data-action="click-&gt;doc-navigation#click"
       data-section-id="operation-get-stations"
       href="https://bump.sh/bump-examples/doc/train-travel-api/operation/operation-get-stations">
    Get a list of train stations
    <span class="operation-verb get">GET</span>
</a></li>

The response for the list-stations call is an object with a data property with
an array of objects but there is no link to expose what those array items are, only

data array[object]

The response is defined as

          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Wrapper-Collection'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Station'
                  - properties:
                      links:
                        allOf:
                          - $ref: '#/components/schemas/Links-Self'
                          - $ref: '#/components/schemas/Links-Pagination'

so it would be more helpful to the reader if this internal Station
schema was called out (so the developer reading the doc
knew the schema name of the items was Station, not just an anonymous object),
and the API doc had an anchor for the Station schema (and the other schemas that are referenced here)
so that they could be referenced by name elsewhere.

<code>data array [<a href='#schema-Station'>Station</a>]</code>

Likewise, the description for the list-trains operation could be more specific
and document the response with an oasdoc link to the Station schema:

The response has a `data` object which is an array containing a page-worth
of {@schema Station} objects.

The tooling could inject an HTML link to the Stations schema.

Notation

I propose specific notation for oasdoc.

oasdoc annotations have the form

annotation ::= '{@' oasdoc-identifier name [ '|' options] '}'

{@op operationId}

{@op operationId|alt text}

Add a hyperlink to the operation named by operationid.
The default hyperlink text is the operationid if no alt text is given.

{@schema schemaName}

Add a hyperlink to the named schema within /components/schemas/schemaName`

{@property schemaName.property}

{@property .property}

The second form may be used within the description text of a schema,
to link to properties relative to that schema.

Add a hyperlink to the named property schema within /components/schemas/schemaName`
This also allows nested properties and arrays,
for example, use

• {@schema schemaName.subproperty}
• {@schema schemaName.subpropertyA.subpropertyB}
• {@schema schemaName.arrayX.items.subpropertyA.arrayY.items.subpropertyB}

to access nested elements.

{@parameter parameterName|in:path}

{@parameter parameterName}

Add a hyperlink to a parameter in /components/parameters
that matches the parameterName. If there are multiple parmaeters
of the same name, select one with in:<location>
using in:path, in:headr, in:query, in:cookie.

{@response responseItemName}

Add a hyperlink to the named response item

{@securityScheme securitySchemeName}

Add a hyperlink to the named security scheme.

{@id identifier}

Establish a name for a document element. This is like
using <a id="identifier"> but does not assume HTML.

If used in the description in an operation that does not have
an operationId, this ID can be used as the well-known
anchor for the operation.

{@link identifier|alt text}

Add a hyperlink to an anchor at a location defined by {@id identifier}

The default hyperlink text is the identifier if no alt text is given.

Well-known anchors

As noted above, different API doc vendors have established
different conventions for the anchors or URIs for the operations and other elements.

I propose oasdoc establish well-known anchor names
for OAS elements. This will allow linking to them from external (non oasdoc) sources
such as tutorials in a devportal.

• For each operation with an operationId, the anchor #op-{operationId}
  may be appended to the API doc URL to jump directly to that operation.
  This is important because vendors use different strategies which
  are sometimes comples and hard to use. See the Redocly
  section above
• For each schema with name schemaName in /components/schemas, the anchor #schema-{schemaName}

As noted, some tool vendors (like bump.sh) do not use anchors; each operation
has it's own URL and the bump.sh user experience manages those links to yield
the equivalemt of a "Single Page App". So supporting such links
would require vendor support, but I think it is possible.

Open Topics

Cross-API Links

Many API providers have suites of APIs, each exposed via separate
API documentation generated from multiple OpenAPI descirptions.
It is common for APIs to be inter-connected. For example,
one API may reference a resource R defined by another API,
and thus it is convenient to link to the corresponding
GET /resources/{resourceId}
operation to fetch the resource that is referenced
locally (for example, in a response object property)
via a resource ID or URL property or an OAS.

such cross-API links are hard to encode, as different tools
and developer portals manage API document catalogs in many ways.
A solution must also account for
API versions (info.version), which adds a level of complexity.

Syntax to be determined.

Subschemas within JSON Schema allOf, oneOf, anyOf, if/then/else

JSON Schema supports conditional and unconditional schema composition
with allOf, oneOf, anyOf, if/then/else keywords.
DIfferent API doc systems yield different rendering
strategies for these constructs.
allOf, oneOf and anyOf each support an array of
subschemas.

oasdoc support for the allOf keyword

The 200 response for the
get-stations operation is defined as

            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Wrapper-Collection'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Station'
                  - properties:
                      links:
                        allOf:
                          - $ref: '#/components/schemas/Links-Self'
                          - $ref: '#/components/schemas/Links-Pagination'

and is rendered as an aggregation of the properties of each item:

data array[object]
  The wrapper for a collection is an array of objects.
links object
  Links to the next and previous pages of a paginated response.

(These property descriptions come from the Wrapper-Collection).

Thus, to link to the data property for a schema defined with allOf,
one can simply link to the schemaName.data property.

oasdoc support for the oneOf keyword

In the Train Travel API, the Payment
schema is defined as

          oneOf:
            - title: Card
              description: A card (debit or credit) to take payment from.
              type: object
              properties:
                ...
            - title: Bank Account
              description: A bank account to take payment from. Must be able to make payments in the currency specified in the payment.
              type: object
              properties:

which bump.sh renders as a panel selector:

One of: Card object Bank Account object

Selecting each option ("Card object" or "Bank Account object" in
the bump.sh experience)
shows the properties of the selected oneOf schema inside a panel listing.

Rendering links to items within oneOf or anyOf constructs is
not straight forward in a complex conditionally-rendered UX.

Neither the Train Travel (or Redocly's Musuem AP)
use the anyOf keyword, but I believe it would be presented in a UX similar
to oneOf and thus not easily accessible via a link.

Other components?

This proposal addresses well-known anchors for operations
(by operationId or {@id ...} ) and named schemas
in the components/schemas object. Is there need for
well-known anchors to other components?
Those elements are already typically represented
in API doc and, to my knowledge, do not merit other links
(for example, does API documentation need to link
to a parameter component, or a response object component
by name)?

[handrews]

This is an interesting idea. My first thought is that it should be a separate specification from the OAS proper, as it is specific to one sort of application (documentation rendering) and not universally essential.

This is not meant to be a comment on the merits of either the general idea or on the specifics of this proposal. Just an observation that this is a different level of abstraction and a different scope of application than the OAS proper.

[DavidBiesack]

Thanks for taking a look and for your perspective, @handrews . I agree such notation is not essential to describing/defining the API contract ... i.e. it would not be part of the JSON Schema that defines OAS 3.x. Thus, the suggested oasdoc constructs would not be required within any OpenAPI document, nor would any changes be needed for other OAS ecosystem tools (SDK generation, mock servers, test case generation, etc.)
I do think it fits into or is analogous the OAS support for CommonMark Markdown documentation.
If it is positioned as an extension or separate specification, there is less incentive for tools to support it uniformly or consistently... I think this would water it down and hinder success and use.
In the age of Agents consuming APIs based on openapi documents, such semantic glue will help such agents (as well as humans) better understand the API and the relationships between operations/schemas.

[dret]

Isn't that the whole idea of a proper extension model? That extensions can be more specific, but still be officially recognized as a useful way to extend the original spec?

[DavidBiesack]

Isn't that the whole idea of a proper extension model? That extensions can be more specific, but still be officially recognized as a useful way to extend the original spec?

@dret By "extension model", what are you referring to exactly? I'm aware of OpenAPI Specification Extensions, whereby one can add x-* extensions to JSON/YAML data element objects within an OAS document, but this does not use that model - this notation is fully contained within the Markdoen description strings. Is there another mechanism you are referring to?

[handrews]

@DavidBiesack I personally (emphasis- all of this is my personal opinion) be relatively OK with treating this somewhat like we treat CommonMark: Pointing to a separate (even if under the OpenAPI Initiative umbrella) specification and saying "you can use this."

At this time, I would prefer to make supporting a new specification a MAY (or perhaps SHOULD) rather than a MUST, analogous to the fact that implementing OAS does not, for example, require implementing Overlays.

As with other things that start out as extensions, if the approach proves successful, we can upgrade that to a MUST in a future version. (I think this is the sort of process that @dret is getting at).

I am quite certain that we previously discussed allowing alternatives to CommonMark (perhaps with a registry of such alternatives) and decided against it as it potentially drastically increased the implementation requirements necessary to retain interoperability. I can't find that discussion or issue now, though, which is annoying as I think we discussed some of the relevant concerns there.

[miqui]

@DavidBiesack Thanks for the proposal. This is quite an interesting one.

[DavidBiesack]

Here is a concrete example.

In our APIs, we have a Debit Cards API with separate operations to lock (freeze) and unlock (unfreeze) a debit card.

These two operations complement each other and it is useful to show how these two operations work in concert by adding hyperlinks.

We currently document this in Markdown:

  /debitCards/{debitCardId}/locked:
    parameters:
      - $ref: '#/components/parameters/debitCardIdPathParam'
    post:
      summary: Lock a Debit Card
      description: >-
        Lock a debit card. ...

        A locked debit card may not be used for new purchases
        until the cardholder [unlocks the card](#op-unlockCustomerDebitCard).
        ...
      operationId: lockCustomerDebitCard

Unfortunately, to make this work, we're forced to employ the convention used by our API doc rendering tool, as shown above. Fortunately, we've been able to extend that tooling to adopt this pattern of using an anchor such as op-unlockCustomerDebitCard for the operation whose operationId is unlockCustomerDebitCard.

But that notation is coupled to our tool.

If someone downloads our OpenAPI document and renders the doc on their own with Redoc or Scalar or bump.sh or openapi-ui or other, links such as [unlocks the card](#op-unlockCustomerDebitCard) will not work within API doc created with those tools.
Thus, I would like the Markdown to be more portable, using the proposed oasdoc notation:

        A locked debit card may not be used for new purchases
        until the cardholder {@op unlockCustomerDebitCard|unlocks the card}.

so that the doc can be rendered with any oasdoc-supported API doc tooling.

SDK code generation

SDK generation tools can also map oasdoc constructs into corresponding
target language conventions. For example, if an SDK tool generates a Java
client library with the unlockCustomerDebitCard function/method,
the notation can be converted into javadoc such as {@link #unlockCustomerDebitCard(....)}

IDE support

IDEs typically have support for quickly navigating to source code from references.
An IDE that supports OpenAPI with the oasdoc notation could allow quickly jumping
from a references such as {@op unlockCustomerDebitCard|unlocks the card}
to the source where the operation unlockCustomerDebitCard is defined.
This would also work for quickly jumping from a schema reference {@schema mySchema} to
the schema definition (or recursively into properties/items in said schemas. (Smart
navigation would find source via allOf/$ref navigation, but as noted above,
it may be ambiguous with oneOf / anyOf / if/then/else composition, though
a good UI could offer navigation options.)

[lornajane]

I like the idea of having a content format that can refer to OpenAPI elements!

I'm not sure how it can fit into the existing OpenAPI specification though. The description field is currently commonmark, a very widely known, used, and supported format with it's own clear specification and an extensive selection of tools. Even for a well-established and specified alternative format, I'm not sure how we'd introduce switching what format can be used in description fields, and I'm not sure about adding the requirement for all tooling to support either description markup.

Perhaps building out some clear specification (this is already a great starting point!) and getting some implementations that use it outside of an openapi description could be a good first step?

[simon-spinner]

I also see the need for inline links in descriptions in specifications I work with. However, I am not convinced that going with a completely new content format is a good idea. Couldn't we exploit what common mark already provides? It is not well defined at the moment what the base URI for relative links in commonmark descriptions in OpenAPI is (at least nothing I am aware of). Most documentation tools translate them unchanged to the output format. Any relative links then become relative to the output document. This allows for hacks assuming that a certain tool always adds certain anchors for operations, schemas, etc.

Could we instead define that relative links in commonmark descriptions should be interpreted relative to the source OpenAPI document? This would allow references such as [](#/components/schemas/Banana) to be used in commonmark descriptions. Tools should then replace those references with their own links in the output document. This could be also extended to links across files. While maybe not as convenient as the original proposal, it doesn't require people to learn a new format.

[handrews]

@simon-spinner

It is not well defined at the moment what the base URI for relative links in commonmark descriptions in OpenAPI is (at least nothing I am aware of).

In 3.2, §4.1.2.2.3 Relative URI References in CommonMark Fields states:

Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description.

In 3.1.1, this same sentence is at the end of §4.6 Relative References in API Description URIs.

So the behavior you're seeing is what the specification requires, I'm afraid.

[handrews]

IIRC, this was done to avoid requiring tooling providers parse CommonMark themselves in order to modify links before handing the text off to CommonMark implementations. The point of using CommonMark was to re-use existing parsers, not have tool providers shoulder more parsing burdens.

[simon-spinner]

CommonMark libraries such as commonmark-js or commonmark-java distinguish between parsing and rendering. Tools can work on an AST returned from the parser, and can do adjustments on it before handing it over to the a renderer. Links could be modified in the AST making it a lot easier for tools.

Even if a tool does not modify the relative links, the impact would not be fatal - it's a dead link in the rendered output. That's the same situation you are faced with if you are using relative links in CommonMark texts in OpenAPI today. The link might work with one tool, but is broken for other tools that make other assumptions.

[DavidBiesack]

Please note that I am not suggesting replacing Markdown (CommonMark), simply extending it and embedding oasdoc notation within Markdown. That is, everything I have suggested can be handled by tooling as a pre-processor of the Markdown, such that the Markdown text is replaced with Markdown links that conforms to the conventions that the API doc is already using tool for creating HTML anchors for operations etc. (This is close to what @simon-spinner added in the second paragraph of their comment)