Adding narrative documentation to OpenAPI specification

Question

As a best practice, I wanted to incorporate some important and critical helpful content into my API specifications

• FAQs related to APIs
• Code template or cookbook to help the consumer to see the code sample to call the API
• API subscription plan
• Service level objectives
• Service layer agreements
• Performance-related details like caching.

I went through the official document of OAM 3.0 seems like there are no direct tags available to define these things.

As per my understanding, these are defined at some other places where APIs are managed. There are not many examples available over the internet to help with this requirement.

I did use Swaggerhub and Anypoint platform to create open API specifications using version 3.0

Answer 1

I don't think OpenAPI specification is expressive enough to cover this, so it is better to cover them in a separate narrative documentation that you link from your specification.

For writing the narrative documentation, documentation management open-source tools include ones like

• Sphinx
• MkDocs

You can add narrative links in the description section of your YAML file.

See an example here.

Example YAML:

openapi: 3.0.2
info:

  title: Open DeFi API
  description: |

    Long Markdown description goes here. 

    Add links here to your documentation here.