1

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

jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
Kundan Saini
  • 87
  • 2
  • 6
  • 15

1 Answers1

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.
Mikko Ohtamaa
  • 82,057
  • 50
  • 264
  • 435
  • Thanks, @Mikko! In any point platform after publishing the APIs in exchange, there are places to define these narrative documents separately from the main API specification. The case of the swagger hub platform as suggested needs a third-party tool to define the narrative documents and link those in the main open API specification. Will this be applicable for RAML also ? – Kundan Saini Dec 30 '22 at 11:27
  • I have not used RAML but I believe it is 100% same. – Mikko Ohtamaa Dec 30 '22 at 16:28