From ec57fe9cac964cff00f5433fb829ce2d6219da7e Mon Sep 17 00:00:00 2001 From: Steven Serrata <9343811+sserrata@users.noreply.github.com> Date: Mon, 13 Nov 2023 16:47:44 -0500 Subject: [PATCH] Prepare release v2.0.0 (#658) * prepare release v2.0.0 * update docs * update compatibility matrix * Update announcement banner * Cherry-pick markdown generator changes #567 from v1 --------- Co-authored-by: Bryan --- CHANGELOG.md | 14 ++ README.md | 136 +++++++------ demo/docs/customization/languagetabs.md | 50 +++-- demo/docs/customization/styling.md | 54 +++--- demo/docs/intro.mdx | 101 ++++++---- demo/docusaurus.config.js | 2 +- demo/package.json | 6 +- lerna.json | 2 +- .../docusaurus-plugin-openapi-docs/README.md | 179 ++++++++++-------- .../package.json | 2 +- .../src/index.ts | 31 ++- .../src/options.ts | 7 + .../src/types.ts | 7 + .../package.json | 4 +- 14 files changed, 350 insertions(+), 245 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c78317d9..9ea0eebba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,17 @@ +## 2.0.0 (Nov 13, 2023) + +High level enhancements + +- First v2.0.0 stable release! + +> Currently only compatible with Docusaurus v2.4.1 -> v2.4.3 + +Other enhancements and bug fixes + +- upgrade to react 18 and demo docusaurus to 2.4.3 ([#656](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/656)) +- allow upgrade to react 18 ([#651](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/651)) +- stop docusaurus support at v2.4.0 ([#650](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/650)) + ## 2.0.0-beta.5 (Oct 23, 2023) High level enhancements diff --git a/README.md b/README.md index c80cc11dd..eb322aaf6 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,39 @@ Key Features: - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. - **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. +- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. -## Installation +## Compatibility Matrix + +| Docusaurus OpenAPI Docs | Docusaurus | +| ----------------------- | --------------- | +| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 1.7.3 (legacy) | `2.0.1 - 2.2.0` | + +## Bootstrapping from Template (new Docusaurus site) + +Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`: + +```bash +npx create-docusaurus@2.4.3 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 start +``` + +## Installation (existing Docusaurus site) Plugin: @@ -53,7 +83,7 @@ yarn add docusaurus-theme-openapi-docs ## Configuring `docusaurus.config.js` (Plugin and theme usage) -Here is an example of properly configuring your `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. +Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. ```js // docusaurus.config.js @@ -66,17 +96,13 @@ Here is an example of properly configuring your `docusaurus.config.js` file for ({ docs: { sidebarPath: require.resolve("./sidebars.js"), - // Please change this to your repo. - // Remove this to remove the "edit this page" links. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", docLayoutComponent: "@theme/DocPage", - docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs + docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs }, blog: { showReadingTime: true, - // Please change this to your repo. - // Remove this to remove the "edit this page" links. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/" }, @@ -91,14 +117,14 @@ Here is an example of properly configuring your `docusaurus.config.js` file for [ 'docusaurus-plugin-openapi-docs', { - id: "apiDocs", - docsPluginId: "classic", + id: "api", // plugin id + docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs config: { - petstore: { // Note: petstore key is treated as the and can be used to specify an API doc instance when using CLI commands - specPath: "examples/petstore.yaml", // Path to designated spec file - outputDir: "api/petstore", // Output directory for generated .mdx docs - sidebarOptions: { - groupPathsBy: "tag", + petstore: { // the referenced when running CLI commands + specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported + outputDir: "api/petstore", // output directory for generated files + sidebarOptions: { // optional, instructs plugin to generate sidebar.js + groupPathsBy: "tag", // group sidebar items by operation "tag" }, }, burgers: { @@ -109,7 +135,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for }, ] ], - themes: ["docusaurus-theme-openapi-docs"], // Allows use of @theme/ApiItem and other components + themes: ["docusaurus-theme-openapi-docs"], // export theme components } ``` @@ -121,37 +147,38 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following | Name | Type | Default | Description | | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | `string` | `null` | A unique document id. | +| `id` | `string` | `null` | A unique plugin ID. | | `docsPluginId` | `string` | `null` | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). | ### config `config` 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. | -| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | -| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | -| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | -| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel | -| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | -| `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. | +| 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 and sidebar files. | +| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | +| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | +| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | +| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel | +| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | +| `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. | +| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. 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 pages when grouping paths by tag. By default, pages are not created for categories, only groups that can be expanded/collapsed.

The supported options are as follows:

`auto`: Sets the category link config type to `generated-index`, building an index page with links to each page in the group.

`tag`: Sets the category link config type to `generated-index` and uses the tag description at the top of the page.

`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. | +| 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.

The supported options are as follows:

`tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description.

`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).

`none`: Does not create pages for categories, only groups that can be expanded/collapsed. | +| `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. | > 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`. @@ -166,6 +193,16 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following > All versions will automatically inherit `sidebarOptions` from the parent/base config. +### markdownGenerators + +`markdownGenerators` can be configured with the following options: + +| Name | Type | Default | Description | +| ------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | +| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.

**Function type:** `(pageData: InfoPageMetadata) => string` | +| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | + ## CLI Usage ```bash @@ -256,29 +293,6 @@ yarn docusaurus gen-api-docs:version petstore:all > 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.1.0 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. diff --git a/demo/docs/customization/languagetabs.md b/demo/docs/customization/languagetabs.md index bdcf89f28..0d9de3d36 100644 --- a/demo/docs/customization/languagetabs.md +++ b/demo/docs/customization/languagetabs.md @@ -10,16 +10,17 @@ description: Configuring language tabs for the API Demo Panel. The Docusaurus OpenAPI docs plugin comes with support for 8 languages which you can render as code snippets on an API operation page. The languages currently supported are: -| Language | Prism Highlighter | Variants | -| -------- | ----------------- | ------------------------------------------------ | -| `curl` | bash | `curl`\* | -| `python` | python | `requests`\*, `http.client` | -| `go` | go | `native`\* | -| `nodejs` | javascript | `axios`\*, `native`, `requests`, `unirest` | -| `ruby` | ruby | `net::http`\* | -| `csharp` | csharp | `restsharp`\*, `httpclient` | -| `php` | php | `curl`\*, `guzzle`, `pecl_http`, `http_request2` | -| `java` | java | `okhttp`\*, `unirest` | +| Language | Prism Highlighter | Variants | +| ------------ | ----------------- | ------------------------------------------------ | +| `curl` | bash | `curl`\* | +| `python` | python | `requests`\*, `http.client` | +| `go` | go | `native`\* | +| `nodejs` | javascript | `axios`\*, `native`, `requests`, `unirest` | +| `ruby` | ruby | `net::http`\* | +| `csharp` | csharp | `restsharp`\*, `httpclient` | +| `php` | php | `curl`\*, `guzzle`, `pecl_http`, `http_request2` | +| `java` | java | `okhttp`\*, `unirest` | +| `powershell` | powershell | `RestMethod`\* | \* Default variant @@ -60,6 +61,7 @@ The demo site disables the `ruby` and `php` languages using the following `langu highlight: "python", language: "python", logoClass: "python", + variant: "requests", }, { highlight: "go", @@ -70,26 +72,34 @@ The demo site disables the `ruby` and `php` languages using the following `langu highlight: "javascript", language: "nodejs", logoClass: "nodejs", + variant: "axios", + }, + { + highlight: "ruby", + language: "ruby", + logoClass: "ruby", }, - // { - // highlight: "ruby", - // language: "ruby", - // logoClass: "ruby", - // }, { highlight: "csharp", language: "csharp", logoClass: "csharp", + variant: "httpclient", + }, + { + highlight: "php", + language: "php", + logoClass: "php", }, - // { - // highlight: "php", - // language: "php", - // logoClass: "php", - // }, { highlight: "java", language: "java", logoClass: "java", + variant: "unirest", + }, + { + highlight: "powershell", + language: "powershell", + logoClass: "powershell", }, ], ``` diff --git a/demo/docs/customization/styling.md b/demo/docs/customization/styling.md index 5ae949146..7a3c34c60 100644 --- a/demo/docs/customization/styling.md +++ b/demo/docs/customization/styling.md @@ -19,54 +19,54 @@ The demo site uses the following CSS to add coloured labels to each request incl ```css /* API Menu Items */ .api-method > .menu__link { -  align-items: center; -  justify-content: start; + align-items: center; + justify-content: start; } .api-method > .menu__link::before { -  width: 50px; -  height: 20px; -  font-size: 12px; -  line-height: 20px; -  text-transform: uppercase; -  font-weight: 600; -  border-radius: 0.25rem; -  border: 1px solid; -  margin-right: var(--ifm-spacing-horizontal); -  text-align: center; -  flex-shrink: 0; -  border-color: transparent; -  color: white; + width: 50px; + height: 20px; + font-size: 12px; + line-height: 20px; + text-transform: uppercase; + font-weight: 600; + border-radius: 0.25rem; + border: 1px solid; + margin-right: var(--ifm-spacing-horizontal); + text-align: center; + flex-shrink: 0; + border-color: transparent; + color: white; } .get > .menu__link::before { -  content: "get"; -  background-color: var(--ifm-color-primary); + content: "get"; + background-color: var(--ifm-color-primary); } .post > .menu__link::before { -  content: "post"; -  background-color: var(--openapi-code-green); + content: "post"; + background-color: var(--openapi-code-green); } .delete > .menu__link::before { -  content: "del"; -  background-color: var(--openapi-code-red); + content: "del"; + background-color: var(--openapi-code-red); } .put > .menu__link::before { -  content: "put"; -  background-color: var(--openapi-code-blue); + content: "put"; + background-color: var(--openapi-code-blue); } .patch > .menu__link::before { -  content: "patch"; -  background-color: var(--openapi-code-orange); + content: "patch"; + background-color: var(--openapi-code-orange); } .head > .menu__link::before { -  content: "head"; -  background-color: var(--ifm-color-secondary-darkest); + content: "head"; + background-color: var(--ifm-color-secondary-darkest); } ``` diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx index fd4dd9520..e5d43e55d 100644 --- a/demo/docs/intro.mdx +++ b/demo/docs/intro.mdx @@ -50,15 +50,46 @@ Key Features: - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. - **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. +- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. --- +## Compatibility Matrix + +| Docusaurus OpenAPI Docs | Docusaurus | +| ----------------------- | --------------- | +| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 1.7.3 (legacy) | `2.0.1 - 2.2.0` | + + :::tip -If you"re building a Docusaurus site from scratch the easiest way to get started is by [installing from template](#installing-from-template). +If you"re building a Docusaurus site from scratch the easiest way to get started is by [installing from template](#bootstrapping-from-template-new-docusaurus-site). ::: -## Installation +## Bootstrapping from Template (new Docusaurus site) + +Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`: + +```bash +npx create-docusaurus@2.4.3 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 start +``` + +## Installation (existing Docusaurus site) :::note Both the plugin and theme are currently designed to pair with a specific Docusaurus release. The Docusaurus badge in the `README.md` and at the top of this page will always reflect the current compatible versions. @@ -114,7 +145,7 @@ plugins: [ To use the theme you"ll need to define it under `themes` in `docusaurus.config.js`: ```javascript title="docusaurus-theme-openapi-docs" -themes: ["docusaurus-theme-openapi-docs"] // exports ApiItem and ApiExplorer +themes: ["docusaurus-theme-openapi-docs"] // exports ApiItem and ApiDemoPanel ``` Finally, you"ll need to replace `@theme/DocItem` with `@theme/ApiItem` as your `docItemComponent`. Where you do this will depend on whether you are using `@docusaurus/preset-classic` or a standalone `@docusaurus/plugin-content-docs` to render your docs (see examples below). @@ -283,27 +314,28 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following | Name | Type | Default | Description | | ------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | `string` | `null` | A unique document id. | +| `id` | `string` | `null` | A unique plugin id. | | `docsPluginId` | `string` | `null` | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). | ### config `config` 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. | -| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | -| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | -| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | -| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. | -| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | -| `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. | +| 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. | +| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | +| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | +| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | +| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. | +| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | +| `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. | +| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. | ### sidebarOptions @@ -313,7 +345,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following | 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 pages when grouping paths by tag. By default, pages are not created for categories, only groups that can be expanded/collapsed.

The supported options are as follows:

`auto`: Sets the category link config type to `generated-index`, building an index page with links to each page in the group.

`tag`: Sets the category link config type to `generated-index` and uses the tag description at the top of the page.

`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.

The supported options are as follows:

`tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description.

`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).

`none`: Does not create pages for categories, only groups that can be expanded/collapsed. | | `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. | @@ -337,28 +369,21 @@ You may optionally configure a `sidebarOptions`. In doing so, an individual `sid All versions will automatically inherit `sidebarOptions` from the parent/base config. ::: -## Installing from Template +### markdownGenerators -Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`: +`markdownGenerators` can be configured with the following options: -```bash -npx create-docusaurus@2.1.0 my-website --package-manager yarn -``` +| Name | Type | Default | Description | +| ------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------| +| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | +| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.

**Function type:** `(pageData: InfoPageMetadata) => string` | +| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | -> 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). +:::info NOTE +If a config option is not provided, its default markdown generator will be used. -```bash -cd my-website -yarn start -``` +This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages. +::: ## Developer Quick Start diff --git a/demo/docusaurus.config.js b/demo/docusaurus.config.js index cfd4fc969..409581e4e 100644 --- a/demo/docusaurus.config.js +++ b/demo/docusaurus.config.js @@ -197,7 +197,7 @@ const config = { announcementBar: { id: "announcementBar_1", content: - "🥳 Support for Docusaurus v2.3.0 is now available in v2.0.0-beta. See badges/releases for latest beta release.", + "🥳 First v2.0.0 stable release! Currently only compatible with Docusaurus v2.4.1 -> v2.4.3", }, }), diff --git a/demo/package.json b/demo/package.json index 41619796b..e3f779d18 100644 --- a/demo/package.json +++ b/demo/package.json @@ -1,6 +1,6 @@ { "name": "demo", - "version": "2.0.0-beta.5", + "version": "2.0.0", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -26,8 +26,8 @@ "@docusaurus/preset-classic": "2.4.3", "@mdx-js/react": "^1.6.22", "clsx": "^1.1.1", - "docusaurus-plugin-openapi-docs": "^2.0.0-beta.5", - "docusaurus-theme-openapi-docs": "^2.0.0-beta.5", + "docusaurus-plugin-openapi-docs": "^2.0.0", + "docusaurus-theme-openapi-docs": "^2.0.0", "prism-react-renderer": "^1.3.1", "react": "^18.2.0", "react-dom": "^18.2.0" diff --git a/lerna.json b/lerna.json index 165ebbd88..db66e79ea 100644 --- a/lerna.json +++ b/lerna.json @@ -1,5 +1,5 @@ { - "version": "2.0.0-beta.5", + "version": "2.0.0", "npmClient": "yarn", "useWorkspaces": true } diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index de4517b2b..5be5e9751 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -25,9 +25,39 @@ Key Features: - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. - **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. +- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. -## Installation +## Compatibility Matrix + +| Docusaurus OpenAPI Docs | Docusaurus | +| ----------------------- | --------------- | +| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 1.7.3 (legacy) | `2.0.1 - 2.2.0` | + +## Bootstrapping from Template (new Docusaurus site) + +Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`: + +```bash +npx create-docusaurus@2.4.3 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 start +``` + +## Installation (existing Docusaurus site) Plugin: @@ -43,51 +73,48 @@ yarn add docusaurus-theme-openapi-docs ## Configuring `docusaurus.config.js` (Plugin and theme usage) -Here is an example of properly configuring your `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. +Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. ```js // docusaurus.config.js { presets: [ - [ - "classic", - /** @type {import('@docusaurus/preset-classic').Options} */ - ({ - docs: { - sidebarPath: require.resolve("./sidebars.js"), - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", - docLayoutComponent: "@theme/DocPage", - docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs - }, - blog: { - showReadingTime: true, - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: - "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/" - }, - theme: { - customCss: require.resolve("./src/css/custom.css") - } - }) - ] -], + [ + "classic", + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + sidebarPath: require.resolve("./sidebars.js"), + editUrl: + "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", + docLayoutComponent: "@theme/DocPage", + docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs + }, + blog: { + showReadingTime: true, + editUrl: + "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/" + }, + theme: { + customCss: require.resolve("./src/css/custom.css") + } + }) + ] + ], plugins: [ + [ 'docusaurus-plugin-openapi-docs', { - id: "apiDocs", - docsPluginId: "classic", + id: "api", // plugin id + docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs config: { - petstore: { // Note: petstore key is treated as the and can be used to specify an API doc instance when using CLI commands - specPath: "examples/petstore.yaml", // Path to designated spec file - outputDir: "api/petstore", // Output directory for generated .mdx docs - sidebarOptions: { - groupPathsBy: "tag", + petstore: { // the referenced when running CLI commands + specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported + outputDir: "api/petstore", // output directory for generated files + sidebarOptions: { // optional, instructs plugin to generate sidebar.js + groupPathsBy: "tag", // group sidebar items by operation "tag" }, }, burgers: { @@ -98,7 +125,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for }, ] ], - themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other components + themes: ["docusaurus-theme-openapi-docs"], // export theme components } ``` @@ -110,37 +137,38 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following | Name | Type | Default | Description | | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | `string` | `null` | A unique document id. | +| `id` | `string` | `null` | A unique plugin id. | | `docsPluginId` | `string` | `null` | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). | ### config `config` 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. | -| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | -| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | -| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | -| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel | -| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | -| `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. | +| 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. | +| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | +| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | +| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | +| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel | +| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | +| `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. | +| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. 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 pages when grouping paths by tag. By default, pages are not created for categories, only groups that can be expanded/collapsed.

The supported options are as follows:

`auto`: Sets the category link config type to `generated-index`, building an index page with links to each page in the group.

`tag`: Sets the category link config type to `generated-index` and uses the tag description at the top of the page.

`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. | +| 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.

The supported options are as follows:

`tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description.

`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).

`none`: Does not create pages for categories, only groups that can be expanded/collapsed. | +| `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. | > 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`. @@ -155,6 +183,16 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following > All versions will automatically inherit `sidebarOptions` from the parent/base config. +### markdownGenerators + +`markdownGenerators` can be configured with the following options: + +| Name | Type | Default | Description | +| ------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | +| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.

**Function type:** `(pageData: InfoPageMetadata) => string` | +| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | + ## CLI Usage ```bash @@ -245,29 +283,6 @@ yarn docusaurus gen-api-docs:version petstore:all > 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.1 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. diff --git a/packages/docusaurus-plugin-openapi-docs/package.json b/packages/docusaurus-plugin-openapi-docs/package.json index a8b7df150..0fe385bc3 100644 --- a/packages/docusaurus-plugin-openapi-docs/package.json +++ b/packages/docusaurus-plugin-openapi-docs/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus-plugin-openapi-docs", "description": "OpenAPI plugin for Docusaurus.", - "version": "2.0.0-beta.5", + "version": "2.0.0", "license": "MIT", "keywords": [ "openapi", diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 41d676e26..ea679f25b 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -92,8 +92,14 @@ export default function pluginOpenAPIDocs( let docPath = docData ? (docData.path ? docData.path : "docs") : undefined; async function generateApiDocs(options: APIOptions, pluginId: any) { - let { specPath, outputDir, template, downloadUrl, sidebarOptions } = - options; + let { + specPath, + outputDir, + template, + markdownGenerators, + downloadUrl, + sidebarOptions, + } = options; // Remove trailing slash before proceeding outputDir = outputDir.replace(/\/$/, ""); @@ -238,12 +244,26 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; \`\`\` `; + const apiPageGenerator = + markdownGenerators?.createApiPageMD ?? createApiPageMD; + const infoPageGenerator = + markdownGenerators?.createInfoPageMD ?? createInfoPageMD; + const tagPageGenerator = + markdownGenerators?.createTagPageMD ?? createTagPageMD; + loadedApi.map(async (item) => { if (item.type === "info") { if (downloadUrl && isURL(downloadUrl)) { item.downloadUrl = downloadUrl; } } + const markdown = + item.type === "api" + ? apiPageGenerator(item) + : item.type === "info" + ? infoPageGenerator(item) + : tagPageGenerator(item); + item.markdown = markdown; if (item.type === "api") { // opportunity to compress JSON // const serialize = (o: any) => { @@ -263,13 +283,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; } if (item.infoId) item.infoPath = infoBasePath; } - const markdown = - item.type === "api" - ? createApiPageMD(item) - : item.type === "info" - ? createInfoPageMD(item) - : createTagPageMD(item); - item.markdown = markdown; const view = render(mdTemplate, item); const utils = render(infoMdTemplate, item); diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index 7123265c9..d2a56805d 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -15,6 +15,12 @@ const sidebarOptions = Joi.object({ sidebarCollapsed: Joi.boolean(), }); +const markdownGenerators = Joi.object({ + createApiPageMD: Joi.function(), + createInfoPageMD: Joi.function(), + createTagPageMD: Joi.function(), +}); + export const OptionsSchema = Joi.object({ id: Joi.string().required(), docsPluginId: Joi.string().required(), @@ -30,6 +36,7 @@ export const OptionsSchema = Joi.object({ hideSendButton: Joi.boolean(), showExtensions: Joi.boolean(), sidebarOptions: sidebarOptions, + markdownGenerators: markdownGenerators, version: Joi.string().when("versions", { is: Joi.exist(), then: Joi.required(), diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 38b0a82da..7c12d0805 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -43,6 +43,13 @@ export interface APIOptions { [key: string]: APIVersionOptions; }; proxy?: string; + markdownGenerators?: MarkdownGenerator; +} + +export interface MarkdownGenerator { + createApiPageMD?: (pageData: ApiPageMetadata) => string; + createInfoPageMD?: (pageData: InfoPageMetadata) => string; + createTagPageMD?: (pageData: TagPageMetadata) => string; } export interface SidebarOptions { diff --git a/packages/docusaurus-theme-openapi-docs/package.json b/packages/docusaurus-theme-openapi-docs/package.json index 189cfb2ad..f2004b4b6 100644 --- a/packages/docusaurus-theme-openapi-docs/package.json +++ b/packages/docusaurus-theme-openapi-docs/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus-theme-openapi-docs", "description": "OpenAPI theme for Docusaurus.", - "version": "2.0.0-beta.5", + "version": "2.0.0", "license": "MIT", "keywords": [ "openapi", @@ -43,7 +43,7 @@ "clsx": "^1.1.1", "copy-text-to-clipboard": "^3.1.0", "crypto-js": "^4.1.1", - "docusaurus-plugin-openapi-docs": "^2.0.0-beta.5", + "docusaurus-plugin-openapi-docs": "^2.0.0", "docusaurus-plugin-sass": "^0.2.3", "file-saver": "^2.0.5", "lodash": "^4.17.20",