Adding narrative documentation to OpenAPI specification [closed] - openapi

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed last month.
Improve this 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.