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.

[miqui]

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