Add extension that handles adding more markdown content to API

[derberg]

Reason/Context

Last 2 weeks I conducted research over few SaaS solutions (ReDoc, Bump, Postman, APIMatic, Readmeio) on how they support AsyncAPI and OpenAPI. I was interested in finding out how they support a use case when you want to enrich your specification with some more markdown content. At the moment there is no widely adopted OAS extension for it. Some solutions just do not support it, and some just add additional functionality on top that locks you in with the vendor and make it hard to migrate.

There was one super nice thing I saw in https://bump.sh/ -> https://help.bump.sh/asyncapi-support#adding-topics-to-your-documentation

x-topics:
  - title: Getting started
    content: Before using the API you need to get an API key by sending us an email.
  - title: Authentication
    content: Send the `X-API-KEY` header with all your requests.
    example: |
      ```
      $ curl \
        -X POST https://api.example.com/endpoint/ \
        -H "X-API-KEY: XXXXXX" \
      ```

You can basically add as many documentation topics as you want, with an additional markdown doc that of course you later can consume as you want in your UI.

I think it is super important to adopt such an extension into the extensions catalog, so vendors later support one way of doing things and make spec adoption easier.
This and other extensions could be a part of something like x-docs extension, and tags object could be part of it maybe?

I'm super interested in what others think.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[MikeRalphson]

We've had a PR over at Widdershins (Mermade/widdershins#327) which would support an x-md- extension (actually the prefix would be configurable) where a markdown path would be read in by the tooling to replace the value of the extension with the contents of the markdown file. The PR doesn't actually touch the AsyncAPI renderer in Widdershins (yet), only the OpenAPI side.

Is this something like you're proposing?

[derberg]

@MikeRalphson I'm thinking here rather about a root level extension only, for overall docs about the API. So you can later of for example render them in left nav.

And support many formats, I know there are many people still liking asciidoc, or pure html could also be imported.

And extension would need to support some basic standard info about the topic, like title, so you do not have to expect markdown file owners to have frontmatter in their docs, because frontmatter in markdown is not part of markdown spec

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️