docusaurus-plugin-openapi-docs 0.0.0-376 → 0.0.0-380

package/README.md

@@ -20,6 +20,13 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2.
 
 The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs by setting `docItemComponent` to `@theme/ApiItem`, a custom component included in the `docusaurus-theme-openapi-docs` theme.
 
+Key Features:
+
+- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
+- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
+- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
+- **Capable:** Supports single, multi and _even micro_ OpenAPI specs.
+
 ## Installation
 
 Plugin:
@@ -71,7 +78,6 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 ],
 
   plugins: [
-    [
       'docusaurus-plugin-openapi-docs',
       {
         id: "apiDocs",
@@ -101,24 +107,42 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 `docusaurus-plugin-openapi-docs` can be configured with the following options:
 
-| Name             | Type     | Default | Description                                                                                                                 |
-| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `specPath`       | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
-| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
-| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
-| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
+| Name              | Type     | Default | Description                                                                                                                 |
+| ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`        | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
+| `ouputDir`        | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `contentDocsPath` | `string` | `null`  | Should be equal to the `path` value set in `plugin-content-docs` or preset.                                                 |
+| `ouputDir`        | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `routeBasePath`   | `string` | `null`  | _Optional:_ Should be equal to the `routeBasePath` value set in `plugin-content-docs or preset (if present).                |
+| `template`        | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
+| `sidebarOptions`  | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
+| `version`         | `string` | `null`  | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`.                                           |
+| `label`           | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                              |
+| `baseUrl`         | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                           |
+| `versions`        | `object` | `null`  | _Optional:_ Set of options for versioning configuration. See below for a list of supported options.                         |
 
 `sidebarOptions` can be configured with the following options:
 
 | Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | -------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`.                                                                                                                                                                                                                                                                                                                   |
-| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/></br>The supported options are as follows: <br/></br> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
+| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/><br/>The supported options are as follows: <br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
 | `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                               |
 | `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-> Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+> You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+
+`versions` can be configured with the following options:
+
+| Name       | Type     | Default | Description                                                                                                              |
+| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `specPath` | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
+| `ouputDir` | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                  |
+| `label`    | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                           |
+| `baseUrl`  | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                        |
+
+> All versions will automatically inherit `sidebarOptions` from the parent/base config.
 
 ## CLI Usage
 
@@ -139,9 +163,11 @@ Commands:
   write-translations [options] [siteDir]                   Extract required translations of your site.
   write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
   docs:version <version>                                   Tag a new docs version
-  gen-api-docs <id>                                        Generates API Docs mdx and sidebars.
-  clean-api-docs <id>                                      Clears the Generated API Docs mdx and sidebars.
-  docs:version:openapi <version>                           Tag a new docs version (openapi)
+  gen-api-docs <id>                                        Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
+  gen-api-docs:version <id:version>                        Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
+  clean-api-docs <id>                                      Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
+  clean-api-docs:version <id:version>                      Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
+                                                           enabled).
 ```
 
 ### Generating OpenAPI Docs
@@ -190,6 +216,61 @@ yarn docusaurus clean-api-docs burgers
 
 > The example above will remove all API docs relative to `burgers`.
 
+### Versioning OpenAPI docs
+
+To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
+
+```bash
+yarn docusaurus gen-api-docs:version <id>:all
+```
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs:version petstore:all
+```
+
+> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
+
+> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
+
+## Installing from Template
+
+Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
+
+```bash
+npx create-docusaurus@2.0.0-beta.21 my-website --package-manager yarn
+```
+
+> When prompted to select a template choose `Git repository`.
+
+Template Repository URL:
+
+```bash
+https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
+```
+
+> When asked how the template repo should be cloned choose "copy" (unless you know better).
+
+```bash
+cd my-website
+yarn
+```
+
+## Developer Quick Start
+
+> Looking to make a contribution? Make sure to checkout out our contributing guide.
+
+After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
+
+```bash
+git clone https://github.com/<your account>/docusaurus-openapi-docs.git
+cd docusaurus-openapi-docs
+yarn
+yarn build-packages
+yarn watch:demo
+```
+
 ## Support
 
-Please read [SUPPORT.md](SUPPORT.md) for details on how to get support for this project.
+Please read [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for details on how to get support for this project.

package/lib/index.js

@@ -27,7 +27,7 @@ function pluginOpenAPIDocs(context, options) {
     let { config } = options;
     let { siteDir } = context;
     async function generateApiDocs(options) {
-        let { specPath, outputDir, template, sidebarOptions } = options;
+        let { specPath, outputDir, contentDocsPath, routeBasePath, template, sidebarOptions, } = options;
         const contentPath = isURL(specPath)
             ? specPath
             : path_1.default.resolve(siteDir, specPath);
@@ -135,8 +135,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 item.markdown = markdown;
                 if (item.type === "api") {
                     item.json = JSON.stringify(item.api);
+                    let infoBasePath = `${outputDir}/${item.infoId}`;
+                    if (routeBasePath) {
+                        infoBasePath = `${routeBasePath}/${outputDir
+                            .split(contentDocsPath)[1]
+                            .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+                    }
                     if (item.infoId)
-                        item.infoPath = `${outputDir}/${item.infoId}`;
+                        item.infoPath = infoBasePath;
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
                 const utils = (0, mustache_1.render)(infoMdTemplate, item);

package/lib/options.js

@@ -9,19 +9,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebarOptions = utils_validation_1.Joi.object({
-    contentDocsPath: utils_validation_1.Joi.string(),
     groupPathsBy: utils_validation_1.Joi.string().valid("tag"),
     categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info"),
     customProps: utils_validation_1.Joi.object(),
     sidebarCollapsible: utils_validation_1.Joi.boolean(),
     sidebarCollapsed: utils_validation_1.Joi.boolean(),
-}).with("groupPathsBy", "contentDocsPath");
+});
 exports.OptionsSchema = utils_validation_1.Joi.object({
     id: utils_validation_1.Joi.string().required(),
     config: utils_validation_1.Joi.object()
         .pattern(/^/, utils_validation_1.Joi.object({
         specPath: utils_validation_1.Joi.string().required(),
         outputDir: utils_validation_1.Joi.string().required(),
+        contentDocsPath: utils_validation_1.Joi.string().required(),
+        routeBasePath: utils_validation_1.Joi.string(),
         template: utils_validation_1.Joi.string(),
         sidebarOptions: sidebarOptions,
         version: utils_validation_1.Joi.string().when("versions", {

package/lib/sidebars/index.js

@@ -20,7 +20,8 @@ function isInfoItem(item) {
 }
 function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, contentDocsPath, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const { contentDocsPath } = options;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const intros = infoItems.map((item) => {

package/lib/types.d.ts

@@ -10,6 +10,8 @@ export interface PluginOptions {
 export interface APIOptions {
     specPath: string;
     outputDir: string;
+    contentDocsPath: string;
+    routeBasePath?: string;
     template?: string;
     sidebarOptions?: SidebarOptions;
     version?: string;
@@ -19,6 +21,15 @@ export interface APIOptions {
         [key: string]: APIVersionOptions;
     };
 }
+export interface SidebarOptions {
+    groupPathsBy?: string;
+    categoryLinkSource?: string;
+    customProps?: {
+        [key: string]: unknown;
+    };
+    sidebarCollapsible?: boolean;
+    sidebarCollapsed?: boolean;
+}
 export interface APIVersionOptions {
     specPath: string;
     outputDir: string;
@@ -80,13 +91,3 @@ export interface ApiNavLink {
     title: string;
     permalink: string;
 }
-export interface SidebarOptions {
-    contentDocsPath?: string;
-    groupPathsBy?: string;
-    categoryLinkSource?: string;
-    customProps?: {
-        [key: string]: unknown;
-    };
-    sidebarCollapsible?: boolean;
-    sidebarCollapsed?: boolean;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-376",
+  "version": "0.0.0-380",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "1a772d94e5e7075dff6f522aef9aab9303a0e007"
+  "gitHead": "3322e621893b40124fed23abd7f7aa8f12fed5af"
 }

package/src/index.ts

@@ -31,7 +31,14 @@ export default function pluginOpenAPIDocs(
   let { siteDir } = context;
 
   async function generateApiDocs(options: APIOptions) {
-    let { specPath, outputDir, template, sidebarOptions } = options;
+    let {
+      specPath,
+      outputDir,
+      contentDocsPath,
+      routeBasePath,
+      template,
+      sidebarOptions,
+    } = options;
 
     const contentPath = isURL(specPath)
       ? specPath
@@ -164,7 +171,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);
-          if (item.infoId) item.infoPath = `${outputDir}/${item.infoId}`;
+          let infoBasePath = `${outputDir}/${item.infoId}`;
+          if (routeBasePath) {
+            infoBasePath = `${routeBasePath}/${outputDir
+              .split(contentDocsPath!)[1]
+              .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+          }
+          if (item.infoId) item.infoPath = infoBasePath;
         }
 
         const view = render(mdTemplate, item);

package/src/options.ts

@@ -8,13 +8,12 @@
 import { Joi } from "@docusaurus/utils-validation";
 
 const sidebarOptions = Joi.object({
-  contentDocsPath: Joi.string(),
   groupPathsBy: Joi.string().valid("tag"),
   categoryLinkSource: Joi.string().valid("tag", "info"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
   sidebarCollapsed: Joi.boolean(),
-}).with("groupPathsBy", "contentDocsPath");
+});
 
 export const OptionsSchema = Joi.object({
   id: Joi.string().required(),
@@ -24,6 +23,8 @@ export const OptionsSchema = Joi.object({
       Joi.object({
         specPath: Joi.string().required(),
         outputDir: Joi.string().required(),
+        contentDocsPath: Joi.string().required(),
+        routeBasePath: Joi.string(),
         template: Joi.string(),
         sidebarOptions: sidebarOptions,
         version: Joi.string().when("versions", {

package/src/sidebars/index.ts

@@ -43,9 +43,10 @@ function groupByTags(
     sidebarCollapsible,
     customProps,
     categoryLinkSource,
-    contentDocsPath,
   } = sidebarOptions;
 
+  const { contentDocsPath } = options;
+
   const apiItems = items.filter(isApiItem);
   const infoItems = items.filter(isInfoItem);
   const intros = infoItems.map((item: any) => {

package/src/types.ts

@@ -30,6 +30,8 @@ export interface PluginOptions {
 export interface APIOptions {
   specPath: string;
   outputDir: string;
+  contentDocsPath: string;
+  routeBasePath?: string;
   template?: string;
   sidebarOptions?: SidebarOptions;
   version?: string;
@@ -40,6 +42,14 @@ export interface APIOptions {
   };
 }
 
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  categoryLinkSource?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}
+
 export interface APIVersionOptions {
   specPath: string;
   outputDir: string;
@@ -112,12 +122,3 @@ export interface ApiNavLink {
   title: string;
   permalink: string;
 }
-
-export interface SidebarOptions {
-  contentDocsPath?: string;
-  groupPathsBy?: string;
-  categoryLinkSource?: string;
-  customProps?: { [key: string]: unknown };
-  sidebarCollapsible?: boolean;
-  sidebarCollapsed?: boolean;
-}