Add better example schemas and custom page docs

[rohit-gohri]

Show examples with:

• Multiple APIs
  • Different Services
  • Different Versions
• Multi File examples Support multi file OpenAPI definitions #23
• Different schames rather all being petstore yaml
• Document custom pages
  • Document hooks separately - Using / for API reference #273
  • Document components separately

[Zenahr]

@rohit-gohri not sure if "custom page docs" is what I'm trying to do but here's my topic:

There doesn't seem to be any docs to embed regular markdown docs into the generated api docs, e.g., to show an "introduction" page before showing the specfile contents. Is this even possible?

[rohit-gohri]

There doesn't seem to be any docs to embed regular markdown docs into the generated api docs, e.g., to show an "introduction" page before showing the specfile contents. Is this even possible?

Do you mean importing a markdown file in the info.description section of the openapi yaml?

[Zenahr]

There doesn't seem to be any docs to embed regular markdown docs into the generated api docs, e.g., to show an "introduction" page before showing the specfile contents. Is this even possible?

Do you mean importing a markdown file in the info.description section of the openapi yaml?

I mean adding a page that is is own element in the generated sidebar.

EDIT: nevermind, wasn't sure on how you were meant to integrate the api docs to the existing documentation. But doing this under the sidebars.js file

            {
              type: 'link',
              label: 'REST API Reference',
              href: '/rest-api-reference/',
            },

works fine, which answers my question too as I can just add articles around this.