cloud-annotations / docusaurus-openapi

🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2.

Cloud Annotations

Important Note: Due to unforseen circumstances, the hosted version of Cloud Annotations (cloud.annotations.ai) is no longer available.

For a similar hosted experience, but focused on education/learning, see Computer Vision Learning Studio.

For instructions on how to run Cloud Annotations using the local file system, see the experimental Iris project.

docusaurus-openapi's Issues

Update template QuickStart guide

Currently, the QuickStart guide provided in the template is a generic Docusaurus guide. We should update the instructions to be more specific to using the OpenAPI extensions.

Loading API file fails on Windows 10

On windows running yarn run start fails due to not being able to load the API file.

Versions:

• windows: Windows 10 Enterprise 20H2
• node: v16.13.0
• npm: 8.1.0
• yarn: 1.22.17

package.json:

{
  ...
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.13",
    "@docusaurus/preset-classic": "2.0.0-beta.13",
    "@mdx-js/react": "^1.6.21",
    "clsx": "^1.1.1",
    "docusaurus-preset-openapi": "^0.3.0",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  },
  ...
}

Error

D:\some\path\docs ❯ yarn run start
yarn run v1.22.17
$ docusaurus start
Starting the development server...
Loading of api failed for "D:\some\path\docs\openapi.json"
undefined
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

D:\some\path\docs ❯ la
d-----       12/13/2021  12:53 PM        1   .docusaurus
d-----       12/13/2021  12:23 PM        1   blog
d-----       12/13/2021  12:23 PM        1   docs
d-----       12/16/2021   5:55 PM        1   node_modules
d-----       12/13/2021  12:23 PM        1   src
d-----       12/13/2021  12:23 PM        1   static
-a----       12/13/2021  12:23 PM      233   .gitignore
-a----       12/13/2021  12:23 PM       89   babel.config.js
-a----       12/16/2021   5:59 PM     3.40KB docusaurus.config.js
-a----       12/13/2021   5:38 PM      298   openapi.json
-a----       12/16/2021   5:47 PM      965   package.json
-a----       12/13/2021  12:23 PM      770   README.md
-a----       12/13/2021  12:23 PM      727   sidebars.js
-a----       12/16/2021   5:55 PM   382.39KB yarn.lock

Expected behaviour

Do not fail to load openapi.json when it exists.

Migrate theme components to TypeScript

Many of the theme components are written in JavaScript. We should work on slowly rewriting components in TypeScript to help catch and prevent bugs.

[Multi-Spec] Category config support

• Use _category_.json collapsed/collapsible to override defaults
• Use _category_.json position to sort

Yaml support?

Does this work with Yaml?

Authorization: config or default to Bearer token approach

Is there any way for the Authorization UI to default to the Bearer token input? Users of my site will need to figure out switching the user/pass inputs to Bearer token. I tried use CSS to alter the presentation but the React logic is not allowing that approach.

[Multi-Spec Umbrella] Support Nested Sidebar Navigation for Multiple API Specifications

I'd like to potentially use this library to render many OpenAPI specs within a single Docusaurus site.

The current implementation only supports top level navigation (with single level drop downs) for multiple OpenAPI specs. This is a limitation of docusaurus itself. If I wanted to render hundreds of specs, it would not scale very well - there's only so much real estate in the top nav.

A viable solution may be to use multiple top-level navs with drop-downs and see how far we can get until facebook/docusaurus#5938 is addressed. At a certain point, though, top level navigation itself doesn't scale even with dropdowns.

Feature Request:

Allow multiple OpenAPI specs to be rendered within the Sidebar of a single route base path.

The current implementation groups operations by tag similar to the Swagger UI within the sidebar.

In order to support N specifications we should be able to render each spec as a category, or, an arbitrary grouping of specs as a category. This will scale better because vertical navigation is less constrained.

Current State

"Logo" "Tutorial" "Auth" "API" "Issue 21" "COS" "YAML" "Blog"
---
pet
	Recursive
	Find pet by ID

Target State

"Logo" "Tutorial" "Auth" "API Reference" "Blog"
---
Group A // specification grouping
	Pet Store // specification description
		pet // operation label/group
			Recursive // operation
			Find pet by ID // operation
	Issue 21 // server
		Missing Summary
Group B
	COS
		Authentication
		Generating an IAM Token
	YAML

A configuration could look something like:

{
  themeConfig:
    /** @type {import('docusaurus-preset-openapi').ThemeConfig} */
    ({
      navbar: {
        // ...
        items: [
          { to: "/auth", label: "Auth", position: "left" },
          {
            label: "API Reference",
            activeBasePath: "api",
            // only relevant at top level
            position: "left",
          },
          // ...
        ],
      },
    }),
  plugins: [
    // can maintain existing functionality
    [
      "docusaurus-plugin-openapi",
      {
        id: "authentication",
        // path to openapi spec
        path: "examples/auth.json",
        // navigation subpath - ties the plugin to the routing
        routeBasePath: "auth",
      },
    ],
    [
      "docusaurus-plugin-openapi",
      {
        // id: null - no need for id for a category
        // navigation subpath - ties the plugin to the routing
        routeBasePath: "api",
        items: [
          {
            label: "Group A",
            routeBasePath: "a",
            items: [
              {
                id: "pet-store",
                label: "Pet Store",
                // becomes api/a/pet-store/[operation]
                // http://localhost:3000/api/a/pet-store/recursive
                routeBasePath: "pet-store",
                // path to openapi spec
                path: "examples/pet-store.json",
              },
              {
                id: "issue21",
                label: "Issue 21",
                routeBasePath: "issue-21",
                path: "examples/openapi-issue-21.json",
              },
            ],
          },
          {
            label: "Group B",
            routeBasePath: "b",
            items: [
              {
                id: "cos",
                label: "COS",
                routeBasePath: "cos",
                path: "examples/cos.json",
              },
              {
                id: "yaml",
                label: "YAML",
                // http://localhost:3000/api/b/yaml/hello-world
                routeBasePath: "yaml",
                path: "examples/yaml.json",
              },
            ],
          },
        ],
      },
    ],
  ],
};

TODO:

• Add recursive folder structure reading & labeling support (#107)
• #133
• #134
• #135
• #136
• #137

Feature request: Endpoints in menu should display method tags

It is common for API documentation to display endpoint methods (GET, POST, etc...) in the menu, example:

[Multi-Spec] Add index spec support

Support for the original _spec_.json idea, but instead follow the Docusaurus category index convention

[Multi-Spec] Plugin options for including/excluding files

With the introduction of multi-spec support, users of the plugin need a way to include/exclude certain files from the directory they provided as path.

Example:

api: {
  path: "examples",
  include: ["**/*.{json,yaml,yml}"],
  exclude: ["test.{json}"]
}

Additionally, when we add support for ingesting mdx pages, we could run into issues where users need to import json or yaml files into their markdown. Having the ability to exclude certain files, gives users room to develop their own conventions for handling this overlap.

For example, users of the plugin could simply ignore any json/yaml file that starts with an underscore from being processed as an API definition, but still import it into their markdown:

api: {
  path: "examples",
  include: ["**/*.{json,yaml,yml}"],
  exclude: ["**/_*.{json,yaml,yml}"]
}

Note: Even with include/exclude, we should still verify that the files processed as API definitions, are valid OpenAPI definitions.

An open question is whether or not to separate markdown include/exclude from API definition include/exclude.

For example:

api: {
  path: "examples",
  include: ["**/*.{json,yaml,yml,md,mdx}"],
  exclude: ["**/_*.{json,yaml,yml,md,mdx}"]
}

vs:

api: {
  path: "examples",
  apiInclude: ["**/*.{json,yaml,yml}"],
  apiExclude: ["**/_*.{json,yaml,yml}"],
  mdxInclude: ["**/*.{md,mdx}"],
  mdxExclude: ["**/_*.{md,mdx}"]
}

Even though include globs have file extensions, a listed file extension does not guarantee it will be parsed. The parser itself has it's own rules for valid extensions (json/yaml/json for api, md/mdx for markdown). This means include: ["**/*.svg"] wouldn't process any files even if there was a api.svg file who's contents was a valid OpenAPI definition. In theory, since there is no file extension overlap between the two types, this should mean that apiInclude/mdxInclude can be replicated by using file extensions.

For example:

api: {
  path: "examples",
  apiInclude: ["api/*.*"],
  apiExclude: ["**/_*.*"],
  mdxInclude: ["markdown/*.*"],
  mdxExclude: []
}

Can be replicated with:

api: {
  path: "examples",
  include: ["api/*.{json,yaml,yml}", "markdown/*.{md,mdx}"],
  exclude: ["**/_*.{json,yaml,yml}"],
}

Both of these configs would process the following:

examples
├── markdown
│   ├── mdx1.md
│   ├── mdx2.mdx
│   ├── mdx3. json
│   └── _mdx4.md
└── api
    ├── api1.md
    ├── api2.mdx
    ├── api3. json
    └── _api4.json

as:

• mdx1.md
• mdx2.mdx
• _mdx4.md
• api3.json

Fails to install with Yarn 3: "Error: Assertion failed: Expected the root to be registered"

I am using Yarn 3.1.1 and on a fresh Docusaurus install, yarn add docusaurus-preset-openapi yields this error:

Error: Assertion failed: Expected the root to be registered

To reproduce, put this pacakge.json in an empty directory and run yarn install && yarn add docusaurus-preset-openapi afterwards:

{
  "name": "my-package",
  "packageManager": "[email protected]",
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.14",
    "@docusaurus/preset-classic": "2.0.0-beta.14",
    "@mdx-js/react": "^1.6.21",
    "clsx": "^1.1.1",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  }
}

However, it works fine with Yarn 1.22 (a version no longer under active development), if this line is removed:

  "packageManager": "[email protected]",

Use of Docusaurus Constants has changed

On Docusaurus Beta 13 they seem to have done changes and now the plugin is broken with error:

Error: Cannot find module '@docusaurus/core/lib/constants'
Require stack:
- /home/anthony/safe_docs/safe/docs/node_modules/docusaurus-plugin-openapi/dist/index.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/init.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/index.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/index.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/commands/build.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/index.js
- /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/bin/docusaurus.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/anthony/safe_docs/safe/docs/node_modules/docusaurus-plugin-openapi/dist/index.js:25:21)
    at Module._compile (node:internal/modules/cjs/loader:1101:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at module.exports (/home/anthony/safe_docs/safe/docs/node_modules/import-fresh/index.js:32:59)
    at normalizePluginConfig (/home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/init.js:46:61)
    at /home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/init.js:138:40
    at Array.map (<anonymous>)
    at initPlugins (/home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/init.js:134:10)
    at loadPlugins (/home/anthony/safe_docs/safe/docs/node_modules/@docusaurus/core/lib/server/plugins/index.js:55:40)

The Docusaurus constants have been moded to @docusaurus/utils.

Please see: facebook/docusaurus#6099

requestBody is not displayed

On a post type endpoint, the schema of the requestBody is not being displayed.

Expected:
requestBody content is displayed.

Actual:
requestBody content is being ignored.

Big assets forming on build

Hi, I'm having a problem with the assets generated by the plugin. I don't know if it is a bug or if there is a way to stop this from happening.

You can see here that when I finish the building process I end up with this huge 12M asset file inside build/assets/js:

When I tried to look inside of it I realized that it had a bunch of names and other data:

So I took a look at the code to see where it is coming from and it seems that the postman-collection or postman-code generators dependencies are using faker to generate fake data, causing this asset to be huge. It this a bug? Is there a way not to include this unnecessary data?

If we cannot avoid this, can we configure the webpack to limit asset sizes?

Thank you in advance. (:

Site description content is not being displayed.

We have important content in the info.description section of the swagger json. This content is not currently being displayed. The documentation makes no mention of displaying static content. Is there somewhere else in the json this content should be placed so that it will display? Is there some other way to include static pages with navigation side by side with the dynamic endpoint content?

Expected:
The content in info.description should be displayed, with sections determined by the markdown.

Actual:
The content is ignored.

openapiPath directory resolution

Interestingly, the openapiPath doesn't work if I just provide a raw string (relative to the root of the repo directory). I have to this to make it work:

module.exports.plugins[0][1].openapiPath = require.resolve(module.exports.plugins[0][1].openapiPath); 

What kind of raw path is expected for it to work? Something like ../../../openapi.json?

Base URL for endpoint test UI & Execute calls

I do not see any config for setting the base url that is used in the endpoint testing UI (2nd column). The default behavior appears to be to use the same url that the site is running on. So when developing it attempts to call localhost... and when deployed it calls that url. I tried adding "servers.url" in the swagger json but that does not appear to be used either. Any input you can provide?

Plugin "docusaurus-plugin-content-docs" error when adding to existing docusaurus site

I added the preset to my docusaurus config

  presets: [
    "docusaurus-preset-openapi",
    /** @type {import('docusaurus-preset-openapi').Options} */
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl:
            'https://github.com/p2-inc/phasetwo-docs/tree/master',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],

but I get the following error when trying to run yarn start

$ yarn start
yarn run v1.22.17
$ docusaurus start
[INFO] Starting the development server...
[ERROR] Error: Plugin "docusaurus-plugin-content-docs" is used 2 times with ID "default".
To use the same plugin multiple times on a Docusaurus site, you need to assign a unique ID to each plugin instance.

The plugin ID is "default" by default. It's possible that the preset you are using already includes a plugin instance, in which case you either want to disable the plugin in the preset (to use a single instance), or assign another ID to your extra plugin instance (to use multiple instances).
    at /Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:20:23
    at Array.forEach (<anonymous>)
    at /Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:18:45
    at Array.forEach (<anonymous>)
    at ensureUniquePluginInstanceIds (/Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/plugins/pluginIds.js:16:35)
    at initPlugins (/Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/plugins/init.js:154:51)
    at loadPlugins (/Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/plugins/index.js:55:40)
    at load (/Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/server/index.js:207:113)
    at async start (/Users/garth/projects/saascrud/phasetwo-docs/node_modules/@docusaurus/core/lib/commands/start.js:39:19)
error Command failed with exit code 1.

I don't understand how to "disable the plugin in the preset" as the error suggests. Has anyone encountered this? Any workarounds? Thank you!

Supporting more than one openapi spec

It seems right now the plugin only supports one spec at a time. I am wondering if it would be possible to add more than one openapi spec at a time. The alternative is to hos the api documentation in multiple docusaurus instances which is not ideal in all cases.

Thank you so much for considering this !!!

Code editor background color bug

Code editor has red background in Chrome (not visible after a production build):

Parameters missing "maxLength", "nullable" props output, Type 'object' no longer notated

In latest v0.3.0 release, object type is no longer notated in the table of parameters (previously, the top level amount param had "object" type notated:

Another couple of props are missing from the output. For example, given this param:

"correlationId": { "maxLength": 40, "type": "string", "description": "Invoice correlation id", "nullable": true, }

Actual output:

Expected:

The "Nullable" and maxLength are being omitted.

install issues

Hey this looks great, but having trouble installing it (new to react && docusaurus). followed the steps on the readme, but it's just 404ing -- is there a build step i need to run?

I'd love to contribute!

Hi there,

I wasn't sure what the best way to reach out was, but I'd love to contribute.

I noticed that the version published to npm was 0.0.12 while what's in master is 0.0.10.

I'd like to add support for OpenAPI's allOf syntax.

Getting Error: Cannot find module 'docusaurus-plugin-openapi' when trying to use as plugin

I'm following the instructions to update to 0.2.2. I installed docusaurus-preset-openapi and uninstalled docusaurus-plugin-openapi as I understood that docusaurus-preset-openapi already includes the plugin.

Just using the preset it works, but when I try to have multiple OpenApi definitions where I need to add a plugin entry I get an Error: Cannot find module 'docusaurus-plugin-openapi'.

My package.json:

{
  "name": "docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "backoffice-rest-api": "openapi-comment-parser ../source/server/rt backoffice_rest_api.json",
    "kiosk-rest-api": "openapi-comment-parser ../source/server/rtkiosk kiosk_rest_api.json",
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "watch": "nodemon -e yaml,js --exec \"openapi-comment-parser src docs/openapi.json && node src/index.js\"",
    "api": "openapi-comment-parser test openapi.json"
  },
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.9",
    "@docusaurus/preset-classic": "2.0.0-beta.9",
    "@mdx-js/react": "^1.6.21",
    "@svgr/webpack": "^5.5.0",
    "clsx": "^1.1.1",
    "docusaurus-dmd-plugin": "file:../docusaurus-dmd-plugin",
    "docusaurus-preset-openapi": "^0.2.2",
    "file-loader": "^6.2.0",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url-loader": "^4.1.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "docusaurus-lunr-search": "^2.1.15",
    "jsdoc-to-markdown": "^7.1.0",
    "mermaid": "^8.13.4",
    "openapi-comment-parser": "^1.0.0",
    "remark-mermaid": "^0.2.0"
  }
}

My docusaurus.config.js

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const remarkMermaid = require("remark-mermaid");
const lunrSearch = require.resolve("docusaurus-lunr-search");

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Docs',
  tagline: 'Enjoy Docs!',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'Docs', // Usually your GitHub org/user name.
  projectName: 'Docs', // Usually your repo name.

  scripts: [
    "https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.8.4/mermaid.min.js",
    "/init.js"
  ],

  plugins: [
    //[
    //  "docusaurus-plugin-openapi", {
    //    id: "backoffice_rest_api",
    //    routeBasePath: "rest-api-backoffice",
    //    path: "./rest_api_backoffice.json",
    //    proxy: {
    //      "/proxy": {
    //        target: "http://localhost:8090",
    //        pathRewrite: { "^/proxy": "" }
    //      }
    //    }
    //  }
    //],
    ["docusaurus-plugin-openapi", {
       id: "kiosk_rest_api",
       path: "rest-api-kiosk",
       openapiPath: "./rest_api_kiosk.json",
       proxy: {
          "/proxy": {
             target: "http://localhost:8091",
             pathRewrite: { "^/proxy": "" }
          }
       }
    }],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_backoffice',
        path: 'js_docs_backoffice',
        routeBasePath: 'js-docs-backoffice',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_kiosk',
        path: 'js_docs_kiosk',
        routeBasePath: 'js-docs-kiosk',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_student',
        path: 'js_docs_student',
        routeBasePath: 'js-docs-student',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    lunrSearch
  ],

  presets: [
    [
      'docusaurus-preset-openapi',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          remarkPlugins: [[remarkMermaid, { simple: true }]]
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        api: {
          path: './rest_api_backoffice.json',
          routeBasePath: 'rest-api-backoffice',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      hideableSidebar: true,
      navbar: {
        hideOnScroll: true,
        title : 'Docs',
        logo: {
          alt : 'Logo',
          src : 'img/logo.svg',
        },
        items: [
          {
            type     : 'doc',
            docId    : 'intro',
            position : 'left',
            label    : 'Tutorial',
          },
          {
            type: 'dropdown',
            label: 'JS Docs',
            position: 'left',
            items: [
              {
                type: 'doc',
                label: 'Backoffice',
                docsPluginId: 'js_docs_backoffice',
                docId: 'intro',
              },
              {
                type: 'doc',
                label: 'Kiosk',
                docsPluginId: 'js_docs_kiosk',
                docId: 'intro',
              },
              {
                type: 'doc',
                label: 'Student',
                docsPluginId: 'js_docs_student',
                docId: 'intro',
              },
            ],
          },
          {
            type: 'dropdown',
            label: 'REST APIs',
            position: 'left',
            items: [
              {
                to: 'rest-api-backoffice',
                label: 'Backoffice',
              },
              {
                to: 'rest-api-kiosk',
                label: 'Kiosk',
              },
              {
                to: 'rest-api-student',
                label: 'Student',
              },
            ],
          },
          {
             to       : '/blog',
             label    : 'Blog',
             position : 'left'
          },
          {
            href     : 'https://gitlab.com',
            label    : 'GitLab',
            position : 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
              },
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitLab',
                href: 'https://gitlab.com',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} Company.`,
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

Also, Is it possible to use just multiple plugins and skip using the docusaurus-preset-openapi preset?

Getting Page not found on API page

Hi I followed the documentation and YouTube video, but I'm getting a Page not found error when trying to access the API page in Docusaurus.

My project doesn't have a running Node server application, is this necessary for the API page to work?

My docusaurus.config.js:

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.

  plugins: [
     ["docusaurus-plugin-openapi", {
        openApiPath: require.resolve("./openapi.json"),
        proxy: {
           "/proxy": {
              target: "http://localhost:4000",
              pathRewrite: { "^/proxy": "" }
           }
        }
     }]
  ],

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'doc',
            docId: 'intro',
            position: 'left',
            label: 'Tutorial',
          },
          {to: 'api/', activeBasePath: 'api', label: 'API', position: 'left'},
          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
              },
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/facebook/docusaurus',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

My package.json:

{
  "name": "docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.9",
    "@docusaurus/preset-classic": "2.0.0-beta.9",
    "@mdx-js/react": "^1.6.21",
    "@svgr/webpack": "^5.5.0",
    "clsx": "^1.1.1",
    "docusaurus-plugin-openapi": "^0.1.0",
    "file-loader": "^6.2.0",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url-loader": "^4.1.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "openapi-comment-parser": "^1.0.0"
  }
}

I have a openapi.json file with content on it.

Build is slow for large (100k+ lines) OpenAPI definitions

Look for bottlenecks in spec processing to see if there are areas for improvement

Breaks when `yarn build`ing with latest docusaurus?

yarn build fails with this error:

Error: Cannot find module '@docusaurus/plugin-content-docs/lib/sidebars/generator'
Require stack:
- /Users/jaime/Code/c20/node_modules/docusaurus-plugin-openapi/lib/sidebars/index.js
- /Users/jaime/Code/c20/node_modules/docusaurus-plugin-openapi/lib/index.js
- ...

The relevant part of my packages.json:

"dependencies": {
    "@docusaurus/core": "^2.0.0-beta.14",
    "@docusaurus/preset-classic": "^2.0.0-beta.14",
    "@docusaurus/types": "^2.0.0-beta.14",
    "docusaurus-preset-openapi": "^0.4.2",
    // ...

So I head to my node_modules/@docusaurus/plugin-content-docs/package.json and I see:

{
  "name": "@docusaurus/plugin-content-docs",
  "version": "2.0.0-beta.fc64c12e4",

It seems yarn is resolving plugin-content-docs to 2.0.0-beta.fc64c12e4, with which docusaurus-openapi breaks.

I have retried yarn install after removing yarn.lock and flushing node_modules, to no avail.

Update website docs page

Currently, the docs in demo are the auto-generated Docusaurus QuickStart tutorial. We should update the docs to be a thorough guide on how to use all the features of the our preset/plugin/theme etc...

Render OAS info as first doc

I'm interested in rendering the info section of a spec file as the first doc displayed. This would allow for displaying the title, version, description and other metadata to help describe the API to the end user. Is there any way to accomplish this with the plugin today? Thanks!

Ensure all published packages have READMEs

Most of the packages have missing/incomplete READMEs

Plugin option for untagged group

Currently, the plugin groups

Default to "API", set to false to leave them ungrouped

Enum values not displayed

We have a few instances of string properties that have enum values.

Example:
"currency": { "enum": [ "USD", "EUR", "GBP" ], "type": "string" },

Expected:
The enum values should be displayed with the value type, like Enum: "USD" "EUR" "GBP".

Actual:
The enum values are ignored.

Render OAS schemas

Right now, in addition to the OAS info not being rendered as an initial page (see #8), the OAS schemas section is not rendered ass well. It would probably be a single sidebar category called "Schemas" with each model underneath it (and the demo panel would be disabled for these pages). Here is an example.

Responses title text should be "Responses", not "Status Codes"

"Status Codes" is an awkward title for the responses section of output. A more common title would be "Responses". Can this be changed? If not, would be ideal if there was an option that we could configure this in docusaurus.config.js.

Multiple API main menu entries

If I want to have multiple API definitions I just have to have multiple plugin entries defined on docusaurus.config.js:

plugins: [
  [
    "docusaurus-plugin-openapi",
    {
      id: "plugin-1",
      openapiPath: require.resolve("./openapi1.json"),
      routeBasePath: "cars",
    },
  ],
  [
    "docusaurus-plugin-openapi",
    {
      id: "plugin-2",
      openapiPath: require.resolve("./openapi2.json"),
      routeBasePath: "bikes",
    },
  ],
];

Then to have multiple menu entries would I have to do this?

{
  to: "cars/",
  activeBasePath: "cars",
  label: "API cars",
  position: "left",
}, {
  to: "bikes/",
  activeBasePath: "bikes",
  label: "API bikes",
  position: "left",
}

A bit confused with the difference between to and activeBasePath.

Document some of the gotchas of MDX

The markdown in OpenAPI definition descriptions is processed by MDX. The results are similar to what would be generated by commonmark, but there are some noticeable differences/gotchas.

What I've come across so far:

• Style attributes must follow the JSX syntax <div style={{ color: "red" }}> vs <div style="color: red;">
• All tags must be closed. For example: Replace <your-name> with your name. will throw an error instead of rendering: Replace with your name..
• Lists can contain html (similar to GitHub flavored markdown), so - Replace <your-name> with your name. will throw an error, because <your-name> will be treaded as html instead of a simple string

Valid commonmark:

List:
- one
- two
- <three>

<div style="background: red; height: 30px; width: 30px;">

Renders:

But the above is invalid MDX and would need to be rewritten as:

List:
- one
- two
- \<three\>

<div style={{ background: "red", height: "30px", width: "30px" }} />

Request body can't be unset

Endpoints with a request body (optional or required) always have an example body prefilled. If this example is deleted, the body is still used in the request/sample code as an empty string.

cURL example on page load:

curl -L -X POST '/v2/store/subscribe' \
--data-raw '{
  "callbackUrl": "https://myserver.com/send/callback/here",
  "eventName": "orderInProgress"
}'

cURL example after deleting code prefilled in editor:

curl -L -X POST '/v2/store/subscribe' \
--data-raw ''

Expected:

curl -L -X POST '/v2/store/subscribe'

Additional feature request:
Since we always provide an example body by default (even when body is optional), it might make sense to remove the + Show optional body and just always show the editor (regardless of optional/required). I believe this would reduce some user confusion of where the body came from on requests where the body was optional.

@simranbentel I think this feature would also fix your issue in #91. Let me know your thoughts 😊

support for trailingSlash=false

Reference: https://docusaurus.io/docs/deployment#trailing-slashes

We use a hosting provider that requires this setting to be false. When false, the OpenAPI plugin does not show its sidebar. I can remove the config to fix the OpenAPI plugin, but that breaks the docs/ sidebar.

Doesn't work with 2.0.0-beta.0

Not really sure why, but when using npm start the page entirely doesn't load, and when using npm run build, the page displays but without the API console on the right-hand side.

Error from ApiStatusCodesTable

Im using this as dependency for another project and tried updating to v0.0.13 but encontered an error when trying to display the API.

It doesn´t ever show the page. I tried downloading this example and compile it myself but no changes. Even the example seems broken to me. I don´t know why you guys are not having the same error as me.. I tracked the error back to commit 193710b (10/12/2020)
I got an easy fix but I didn´t explore it deeply.

It seems that from that commit you are using ApiRequestBodyTable to display ApiStatusCodeTable. But at ApiStatusCodes the body not always provides a content.. And since from ApiRequestTableBodyTable we have this code:

  if (body === undefined) {
    return null;
  }

  // NOTE: We just pick a random content-type.
  // How common is it to have multiple?

  const randomFirstKey = Object.keys(body.content)[0];

It fails to access 0 index of undefined.

Easy fix:

  if (body?.content === undefined) {
    return null;
  }
  const randomFirstKey = Object.keys(body.content)[0];

I will make a pull request if it seams fair.

Missing status code details

On the status codes, information like description is missing:

On README the status code description appears:

My package.json:

{
  "name": "tdsdocs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "watch": "nodemon -e yaml,js --exec \"openapi-comment-parser src docs/openapi.json && node src/index.js\"",
    "api": "openapi-comment-parser test openapi.json"
  },
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.9",
    "@docusaurus/preset-classic": "2.0.0-beta.9",
    "@mdx-js/react": "^1.6.21",
    "@svgr/webpack": "^5.5.0",
    "clsx": "^1.1.1",
    "docusaurus-plugin-openapi": "^0.1.0",
    "file-loader": "^6.2.0",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url-loader": "^4.1.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "openapi-comment-parser": "^1.0.0"
  }
}

UI quirks, new?

The narrow tables in the middle and the menu indicator in the sidebar are not in the screenshot in the readme. Are these new after the recent upgrade? Or maybe something about how I launched the demo?

Make security scheme case-insensitive

As per @simranbentel in #67, It is common for the security scheme for bearer auth to be capitalized as Bearer. Looking in to this, a comment in OAI/OpenAPI-Specification#1876 noted that according to RFC7235, the authentication scheme is a case-insensitive token.

We should update our scheme detection code to reflect this.

Error in openapiPath?

Hey there, I don't know if this is a issue or if I did something wrong, but, I followed the steps and I get an error:

I started to play some things and I added a json stringify in the openapiPath:

After that the error disappeared, but I couldn't see the API page:

Did I do something wrong or is this a bug?
Thanks in advance!

Allow expandable row on Status Code table

For now the only way to know how returned data looks like consist in waiting for a query.

Could it be possible to add an expand button at the end of a status row that would show a response example ?
We can already see what a request body looks like in docusaurus-plugin-openapi/src/theme/ApiDemoPanel/Body/index.js, is it possible to also display how response body looks like on docusaurus-plugin-openapi/src/theme/ApiStatusCodesTable/index.js?

If you need more details feel free to ask.

Nested tags

Is it possible to have nested tags, and then have them displayed on the navigation menu?

For example if I would like to have for example cat and dog bellow pets and then have the endpoints bellow each one:

Add a convenient "bootstrap project" CLI command

A new user trying to use OpenAPI in there Docusaurus project should be able to easily create a new project by running an npx command.

Similar to create-docusaurus and create-react-app:

npx create-docusaurus@latest my-website classic

// or 

npx create-react-app my-app

Options

1) Custom Docusaurus template

The create-docusaurus command allows for passing a custom template in the form of a GitHub repo:

npx create-docusaurus@latest my-website https://github.com/cloud-annotations/docusaurus-openapi-template.git

Pros

• We don't need to write/maintain our own CLI

Cons

• We need to maintain a separate repo with the template
• The CLI command is a bit long (not as easy to type by hand or from memory)

2) Custom CLI

We could write our own CLI that bootstraps a project:

npx create-docusaurus-openapi my-website

Pros

• Writing our own CLI would give us the option to keep both CLI and template code in this repo
• Shorter CLI command

Cons

• We need to write/maintain our own CLI

3) Feature request for create-docusaurus

Create a feature request for adding the option to use NPM packages as templates similar to create-react-app.

For example, creating a package docusaurus-template-openapi, would allow:

npx create-docusaurus@latest my-website openapi

[Multi-Spec] Load markdown pages

Upgrade this plugin to docusaurus beta

We have used this plugin that meets our requirements the way we want to create and manage the entire platform documentation. We have got this plugin working end-to-end for the Alpha version of Docusaurus but it's being deprecated and we couldn't find a way to make it work for the Beta version of Docusaurus.

We are really looking forward someone who can make this plugin work for the Beta version of Docusaurus and we are happy to sponsor the development charges. We will then open-source it here for the community.

Please get back to me if this is something you can help us and the community. We really believe this plug-in is very valuable for the community.

Allow markdown in paramater descriptions

I want to be able to document query parameters like this:

To be able to do this I would need markdown support for description in parameters.