diff --git a/CHANGELOG.md b/CHANGELOG.md index b20f9da73..8e1f9c2c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,41 @@ +## 3.0.0 (Jul 3, 2024) + +First official v3 release! + +- Added support for Docusaurus v3.0.1 - v3.4.0 (and hopefully beyond) +- Complete feature parity with v2.2.0 including bug fixes + +Other enhancements and bug fixes + +- Support absolute or relative downloadUrl ([#865](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/865)) +- fix typo in attribute ([#864](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/864)) +- uncomment version dropdown styles ([#863](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/863)) +- Support flexible code snippet ordering and options ([#862](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/862)) +- migrate back to canonical postman deps ([#860](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/860)) +- Support custom downloadUrl for versions ([#859](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/859)) +- [V3] Fix tagGroup display when showSchemas is configured ([#852](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/852)) +- check to avoid tagGroup config before concat operation, api, schemas ([#853](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/853)) +- handle various additionalProperties cases ([#803](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/803)) +- cleanup legacy ApiDemoPanel component +- cleanup legacy docusaurus config +- upgrade to docusaurus 3.4.0 ([#850](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/850)) +- support empty object schema type ([#849](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/849)) +- ensure readOnly/writeOnly are evaluated first ([#848](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/848)) +- transparent bg color when showing placeholder ([#847](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/847)) +- Bug/set accept ([#846](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/846)) +- Implement the `x-tags` extension for schema objects ([#837](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/837)) +- fix col row padding footer&pagination ([#810](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/810)) +- Update index.tsx ([#839](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/839)) +- fix: markdown table within the description attribute cannot be rendered correctly ([#831](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/831)) +- upgrade demo to docusaurus 3.3.2 ([#822](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/822)) +- add missing types and cast ref to LegacyRef ([#818](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/818)) +- Add option to disable frontmatter api prop compression ([#800](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/800)) +- preventing to send form onClick left/right arrows in SchemaTabs component ([#796](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/796)) +- Ensure sidebars.ts and schemas are properly cleaned ([#817](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/817)) +- changed theme and plugin to headings ([#786](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/786)) +- Allow custom plugin to render ([#784](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/784)) +- Remove scrollbar width for Tab components ([#785](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/785)) + ## 3.0.0-beta.10 (Mar 25, 2024) High level enhancements diff --git a/README.md b/README.md index c7b689d66..a1a61c7bf 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@
-OpenAPI plugin for generating API reference docs in Docusaurus v2. +OpenAPI plugin for generating API reference docs in Docusaurus v3.

@@ -28,11 +28,11 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2. ## Overview -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. +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 when combined with the `docusaurus-theme-openapi-docs` theme. Key Features: -- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. +- **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. - **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. @@ -41,16 +41,16 @@ Key Features: | Docusaurus OpenAPI Docs | Docusaurus | | ----------------------- | --------------- | -| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` | -| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 3.0.0 (current) | `3.0.1 - 3.4.0` | +| 2.2.0 (legacy) | `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`: +Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`: ```bash -npx create-docusaurus@2.4.3 my-website --package-manager yarn +npx create-docusaurus@3.4.0 my-website --package-manager yarn ``` > When prompted to select a template choose `Git repository`. @@ -61,57 +61,59 @@ Template Repository URL: https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git ``` -> When asked how the template repo should be cloned choose "copy" (unless you know better). +> When asked how the template repo should be cloned choose "copy". ```bash cd my-website yarn start ``` +If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API! + ## Installation (existing Docusaurus site) -Plugin: +> 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. + +### Plugin ```bash yarn add docusaurus-plugin-openapi-docs ``` -Theme: +### Theme ```bash yarn add docusaurus-theme-openapi-docs ``` -## Configuring `docusaurus.config.js` (Plugin and theme usage) +## Configuring `docusaurus.config.ts` (Plugin and theme usage) -Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. +Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. -```js -// docusaurus.config.js +> Note: Instructions may differ slightly for sites that haven't migrated to typescript. + +```typescript +// docusaurus.config.ts +// note that parts of the complete config were left out for brevity +import type * as Preset from "@docusaurus/preset-classic"; +import type { Config } from "@docusaurus/types"; +import type * as Plugin from "@docusaurus/types/src/plugin"; +import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"; { presets: [ [ "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/" + sidebarPath: "./sidebars.ts", + docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi }, theme: { - customCss: require.resolve("./src/css/custom.css") - } - }) - ] + customCss: "./src/css/custom.css", + }, + } satisfies Preset.Options, + ], ], plugins: [ @@ -119,19 +121,15 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu 'docusaurus-plugin-openapi-docs', { id: "api", // plugin id - docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs + docsPluginId: "classic", // configured for preset-classic config: { - 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" + petstore: { + specPath: "examples/petstore.yaml", + outputDir: "docs/petstore", + sidebarOptions: { + groupPathsBy: "tag", }, - }, - burgers: { - specPath: "examples/food/burgers/openapi.yaml", - outputDir: "api/food/burgers", - } + } satisfies OpenApiPlugin.Options, } }, ] @@ -226,11 +224,12 @@ 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 Tag a new docs version - gen-api-docs Generates OpenAPI docs in MDX file format and sidebar.js (if enabled). - gen-api-docs:version Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled). - clean-api-docs Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled). - clean-api-docs:version Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if + gen-api-docs [options] Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled). + gen-api-docs:version [options] Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled). + clean-api-docs [options] Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled). + clean-api-docs:version [options] Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts + (if enabled) ``` ### Generating OpenAPI Docs @@ -252,10 +251,10 @@ yarn docusaurus gen-api-docs Example: ```bash -yarn docusaurus gen-api-docs burgers +yarn docusaurus gen-api-docs petstore ``` -> The example above will only generate API docs relative to `burgers`. +> The example above will only generate API docs relative to `petstore`. ### Cleaning API Docs @@ -274,7 +273,7 @@ yarn docusaurus clean-api-docs Example: ```bash -yarn docusaurus clean-api-docs burgers +yarn docusaurus clean-api-docs petstore ``` > The example above will remove all API docs relative to `burgers`. diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx index 1143ae386..cc19f914d 100644 --- a/demo/docs/intro.mdx +++ b/demo/docs/intro.mdx @@ -22,7 +22,7 @@ tags:
-OpenAPI plugin for generating API reference docs in Docusaurus v2. +OpenAPI plugin for generating API reference docs in Docusaurus v3.

@@ -43,11 +43,11 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2. ## Overview -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, interactive API reference docs. +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 when combined with the `docusaurus-theme-openapi-docs` theme. Key Features: -- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. +- **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. - **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. @@ -58,8 +58,8 @@ Key Features: | Docusaurus OpenAPI Docs | Docusaurus | | ----------------------- | --------------- | -| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` | -| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 3.0.0 (current) | `3.0.1 - 3.4.0` | +| 2.2.0 (legacy) | `2.4.1 - 2.4.3` | | 1.7.3 (legacy) | `2.0.1 - 2.2.0` | @@ -72,7 +72,7 @@ If you"re building a Docusaurus site from scratch the easiest way to get started 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 +npx create-docusaurus@3.4.0 my-website --package-manager yarn ``` > When prompted to select a template choose `Git repository`. @@ -90,6 +90,8 @@ cd my-website yarn start ``` +If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API! + ## Installation (existing Docusaurus site) :::note @@ -110,98 +112,126 @@ yarn add docusaurus-theme-openapi-docs ## Configuration -### Configuring the plugin +## Configuring `docusaurus.config.ts` (Plugin and theme usage) -The plugin configuration is comprised of options that are read by the CLI while generating and cleaning API docs. +Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. :::note -See [plugin configuration options](#plugin-configuration-options) for a more thorough reference. + Instructions may differ slightly for sites that haven't migrated to typescript. ::: -The following is an example configuration to help get you started. - -```javascript title="docusaurus-plugin-openapi-docs" -plugins: [ - [ - "docusaurus-plugin-openapi-docs", - { - id: "openapi", - docsPluginId: "", // e.g. "classic" or the plugin-content-docs id - config: { - petstore: { // "petstore" is considered the that you will reference in the CLI - specPath: "examples/petstore.yaml", // path or URL to the OpenAPI spec - outputDir: "api/petstore", // output directory for generated *.mdx and sidebar.js files - sidebarOptions: { - groupPathsBy: "tag", // generate a sidebar.js slice that groups operations by tag - }, +```typescript +// docusaurus.config.ts +// note that parts of the complete config were left out for brevity +import type * as Preset from "@docusaurus/preset-classic"; +import type { Config } from "@docusaurus/types"; +import type * as Plugin from "@docusaurus/types/src/plugin"; +import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"; + +{ + presets: [ + [ + "classic", + { + docs: { + sidebarPath: "./sidebars.ts", + docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi + }, + theme: { + customCss: "./src/css/custom.css", + }, + } satisfies Preset.Options, + ], + ], + + plugins: [ + [ + 'docusaurus-plugin-openapi-docs', + { + id: "api", // plugin id + docsPluginId: "classic", // configured for preset-classic + config: { + petstore: { + specPath: "examples/petstore.yaml", + outputDir: "docs/petstore", + sidebarOptions: { + groupPathsBy: "tag", + }, + } satisfies OpenApiPlugin.Options, } - } - }, - ] -], + }, + ] + ], + themes: ["docusaurus-theme-openapi-docs"], // export theme components +} ``` -### Configuring the theme +> Note: You may optionally configure a dedicated `@docusaurus/plugin-content-docs` instance for use with `docusaurus-theme-openapi-docs` by setting `docItemComponent` to `@theme/ApiItem`. -To use the theme you"ll need to define it under `themes` in `docusaurus.config.js`: +## Plugin Configuration Options -```javascript title="docusaurus-theme-openapi-docs" -themes: ["docusaurus-theme-openapi-docs"] // exports ApiItem and ApiDemoPanel -``` +The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options: -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). +| Name | Type | Default | Description | +| -------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `string` | `null` | A unique plugin ID. | +| `docsPlugin` | `string` | `@docusaurus/plugin-content-docs` | The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by `docsPluginId` is a `preset`). | +| `docsPluginId` | `string` | `null` | The plugin ID associated with the `preset` or configured `docsPlugin` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). | -:::note -The `@theme/ApiItem` component is designed to be a drop-in replacement for `@theme/DocItem` that supports rendering OpenAPI documentation while maintaining backwards compatibility with non-API docs. In other words, it can be used for rendering both API _and_ non-API docs. -::: +### config -```javascript title="preset-classic example" -presets: [ - [ - "classic", - ({ - docs: { - sidebarPath: require.resolve("./sidebars.js"), - editUrl: - "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", - docLayoutComponent: "@theme/DocPage", - // highlight-next-line - docItemComponent: "@theme/ApiItem" // add @theme/ApiItem here - }, - blog: { - showReadingTime: true, - editUrl: - "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/" - }, - theme: { - customCss: require.resolve("./src/css/custom.css") - } - }) - ] -] -``` +`config` can be configured with the following options: -```javascript title="plugin-content-docs example" -plugins: [ - [ - "@docusaurus/plugin-content-docs", - { - path: "docs", - breadcrumbs: true, - routeBasePath: "docs", - include: ["**/*.md", "**/*.mdx"], - sidebarPath: "sidebars.js", - docLayoutComponent: "@theme/DocPage", - // highlight-next-line - docItemComponent: "@theme/ApiItem", // add @theme/ApiItem here - }, - ], - ], -``` +| 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. | +| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. | + +`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` and `tagGroup`. | +| `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`. + +`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. | -### Complete example +> All versions will automatically inherit `sidebarOptions` from the parent/base config. -For a complete example of how to configure `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` see the [demo configuration](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/docusaurus.config.js). +### 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` | +| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | ## CLI Usage @@ -224,34 +254,27 @@ 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 Tag a new docs version - gen-api-docs Generates OpenAPI docs in MDX file format and sidebar.js (if enabled). - gen-api-docs:version Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled). - clean-api-docs Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled). - clean-api-docs:version Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if + gen-api-docs [options] Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled). + gen-api-docs:version [options] Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled). + clean-api-docs [options] Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled). + clean-api-docs:version [options] Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts + (if enabled) ``` -:::tip -If you're configuring multiple `docusaurus-plugin-openapi-docs` instances use the `-p` or `--plugin-id` option to specify which plugin instance to run the commands against. +### Generating OpenAPI Docs -``` -Options: - -p, --plugin-id OpenAPI docs plugin ID. - -h, --help display help for command -``` +To generate all OpenAPI docs, run the following command from the root directory of your project: +:::note +This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config. ::: -### Generating OpenAPI Docs - -> The following command will generate API docs for all of the OpenAPI specifications referenced in your `docusaurus-plugin-openapi-docs` config. - ```bash yarn docusaurus gen-api-docs all ``` - -> The following command will generate API docs for a specific `id`: +You may also generate OpenAPI docs for a single path or OAS by specifying the unique `id`: ```bash yarn docusaurus gen-api-docs @@ -265,15 +288,13 @@ yarn docusaurus gen-api-docs petstore ### Cleaning API Docs -Occasionally you may need to clean and re-generate API docs, especially following changes to your OpenAPI specification(s). - -> The following command will clean all API docs referenced in your `docusaurus-plugin-openapi-docs` config. +To clean/remove all API Docs, run the following command from the root directory of your project: ```bash yarn docusaurus clean-api-docs all ``` -> The following command will clean API docs for a specific `id`: +You may also remove a particular set of API docs by specifying the unique `id` of your desired spec instance. ```bash yarn docusaurus clean-api-docs @@ -309,85 +330,6 @@ Substitue `all` with a specific version ID to generate/clean a specific version. See [versions options](#versions) for a list of available options. For a complete example of how to configure versining see the [demo configuration](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/docusaurus.config.js#L190). -## Plugin Configuration Options - -The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options: - -| Name | Type | Default | Description | -| ------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | -| `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. | -| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. | - -### sidebarOptions - - -`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.

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. | - -:::info TIP -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 - -`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. | - -:::info NOTE -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` | -| `createSchemaPageMD`| `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | - -:::info NOTE -If a config option is not provided, its default markdown generator will be used. - -This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages. -::: - ## Developer Quick Start > Looking to make a contribution? Make sure to checkout out our contributing guide. diff --git a/demo/package.json b/demo/package.json index 6627631fc..2f4360cbf 100644 --- a/demo/package.json +++ b/demo/package.json @@ -1,6 +1,6 @@ { "name": "demo", - "version": "3.0.0-beta.10", + "version": "3.0.0", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -25,8 +25,8 @@ "@docusaurus/plugin-google-gtag": "3.4.0", "@docusaurus/preset-classic": "3.4.0", "clsx": "^1.1.1", - "docusaurus-plugin-openapi-docs": "^3.0.0-beta.10", - "docusaurus-theme-openapi-docs": "^3.0.0-beta.10", + "docusaurus-plugin-openapi-docs": "^3.0.0", + "docusaurus-theme-openapi-docs": "^3.0.0", "prism-react-renderer": "^2.3.0", "react": "^18.2.0", "react-dom": "^18.2.0" diff --git a/lerna.json b/lerna.json index 845fbd4c0..7a3bcdd2e 100644 --- a/lerna.json +++ b/lerna.json @@ -1,4 +1,4 @@ { - "version": "3.0.0-beta.10", + "version": "3.0.0", "npmClient": "yarn" } diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index a775eeccb..a1a61c7bf 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -6,23 +6,33 @@
-OpenAPI plugin for generating API reference docs in Docusaurus v2. +OpenAPI plugin for generating API reference docs in Docusaurus v3. + + +

+ +[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [![npm latest package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/latest.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm downloads](https://img.shields.io/npm/dm/docusaurus-plugin-openapi-docs.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm canary package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/canary.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm beta package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/beta.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) +
+[![build](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/actions/workflows/validate.yaml/badge.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/actions/workflows/validate.yaml) [![prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Cypress.io](https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg)](https://www.cypress.io/) [![jest](https://jestjs.io/img/jest-badge.svg)](https://github.com/facebook/jest) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/CONTRIBUTING.md#pull-requests) +

-delete-a-pet +

+--- + ## Overview -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. +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 when combined with the `docusaurus-theme-openapi-docs` theme. Key Features: -- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0. +- **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. - **Flexible:** Supports single, multi and _even micro_ OpenAPI specs. @@ -31,16 +41,16 @@ Key Features: | Docusaurus OpenAPI Docs | Docusaurus | | ----------------------- | --------------- | -| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` | -| 2.0.x (current) | `2.4.1 - 2.4.3` | +| 3.0.0 (current) | `3.0.1 - 3.4.0` | +| 2.2.0 (legacy) | `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`: +Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`: ```bash -npx create-docusaurus@2.4.3 my-website --package-manager yarn +npx create-docusaurus@3.4.0 my-website --package-manager yarn ``` > When prompted to select a template choose `Git repository`. @@ -51,57 +61,59 @@ Template Repository URL: https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git ``` -> When asked how the template repo should be cloned choose "copy" (unless you know better). +> When asked how the template repo should be cloned choose "copy". ```bash cd my-website yarn start ``` +If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API! + ## Installation (existing Docusaurus site) -Plugin: +> 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. + +### Plugin ```bash yarn add docusaurus-plugin-openapi-docs ``` -Theme: +### Theme ```bash yarn add docusaurus-theme-openapi-docs ``` -## Configuring `docusaurus.config.js` (Plugin and theme usage) +## Configuring `docusaurus.config.ts` (Plugin and theme usage) -Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. +Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage. -```js -// docusaurus.config.js +> Note: Instructions may differ slightly for sites that haven't migrated to typescript. + +```typescript +// docusaurus.config.ts +// note that parts of the complete config were left out for brevity +import type * as Preset from "@docusaurus/preset-classic"; +import type { Config } from "@docusaurus/types"; +import type * as Plugin from "@docusaurus/types/src/plugin"; +import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"; { presets: [ [ "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/" + sidebarPath: "./sidebars.ts", + docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi }, theme: { - customCss: require.resolve("./src/css/custom.css") - } - }) - ] + customCss: "./src/css/custom.css", + }, + } satisfies Preset.Options, + ], ], plugins: [ @@ -109,19 +121,15 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu 'docusaurus-plugin-openapi-docs', { id: "api", // plugin id - docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs + docsPluginId: "classic", // configured for preset-classic config: { - 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" + petstore: { + specPath: "examples/petstore.yaml", + outputDir: "docs/petstore", + sidebarOptions: { + groupPathsBy: "tag", }, - }, - burgers: { - specPath: "examples/food/burgers/openapi.yaml", - outputDir: "api/food/burgers", - } + } satisfies OpenApiPlugin.Options, } }, ] @@ -136,10 +144,11 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options: -| Name | Type | Default | Description | -| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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"). | +| Name | Type | Default | Description | +| -------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `string` | `null` | A unique plugin ID. | +| `docsPlugin` | `string` | `@docusaurus/plugin-content-docs` | The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by `docsPluginId` is a `preset`). | +| `docsPluginId` | `string` | `null` | The plugin ID associated with the `preset` or configured `docsPlugin` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). | ### config @@ -148,7 +157,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following | 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. | +| `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) | @@ -166,7 +175,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`. | +| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. | | `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. | @@ -189,11 +198,12 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following `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` | +| 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` | +| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | ## CLI Usage @@ -214,11 +224,12 @@ 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 Tag a new docs version - gen-api-docs Generates OpenAPI docs in MDX file format and sidebar.js (if enabled). - gen-api-docs:version Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled). - clean-api-docs Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled). - clean-api-docs:version Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if + gen-api-docs [options] Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled). + gen-api-docs:version [options] Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled). + clean-api-docs [options] Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled). + clean-api-docs:version [options] Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts + (if enabled) ``` ### Generating OpenAPI Docs @@ -240,10 +251,10 @@ yarn docusaurus gen-api-docs Example: ```bash -yarn docusaurus gen-api-docs burgers +yarn docusaurus gen-api-docs petstore ``` -> The example above will only generate API docs relative to `burgers`. +> The example above will only generate API docs relative to `petstore`. ### Cleaning API Docs @@ -262,7 +273,7 @@ yarn docusaurus clean-api-docs Example: ```bash -yarn docusaurus clean-api-docs burgers +yarn docusaurus clean-api-docs petstore ``` > The example above will remove all API docs relative to `burgers`. @@ -299,6 +310,20 @@ yarn build-packages yarn watch:demo ``` +## Credits + +Special thanks to @bourdakos1 (Nick Bourdakos), the author of [docusaurus-openapi](https://github.com/cloud-annotations/docusaurus-openapi), which this project is heavily based on. + +For more insight into why we decided to completely fork see [#47](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/47) + +## Contributors + + + + + ## Support -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. +See [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for our support agreement and guidelines. + +If you believe you found a bug or have an idea you'd like to suggest you may [report an issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/new/choose) or [start a discussion](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/discussions/new/choose). diff --git a/packages/docusaurus-plugin-openapi-docs/package.json b/packages/docusaurus-plugin-openapi-docs/package.json index e7e71f910..76eb84537 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": "3.0.0-beta.10", + "version": "3.0.0", "license": "MIT", "keywords": [ "openapi", @@ -41,8 +41,6 @@ "@docusaurus/plugin-content-docs": "^3.0.1", "@docusaurus/utils": "^3.0.1", "@docusaurus/utils-validation": "^3.0.1", - "openapi-to-postmanv2": "^4.21.0", - "postman-collection": "^4.4.0", "@redocly/openapi-core": "^1.10.5", "chalk": "^4.1.2", "clsx": "^1.1.1", @@ -52,6 +50,8 @@ "json5": "^2.2.3", "lodash": "^4.17.20", "mustache": "^4.2.0", + "openapi-to-postmanv2": "^4.21.0", + "postman-collection": "^4.4.0", "slugify": "^1.6.5", "swagger2openapi": "^7.0.8", "xml-formatter": "^2.6.1" diff --git a/packages/docusaurus-theme-openapi-docs/package.json b/packages/docusaurus-theme-openapi-docs/package.json index e6c6e671b..5a90a09d0 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": "3.0.0-beta.10", + "version": "3.0.0", "license": "MIT", "keywords": [ "openapi", @@ -38,17 +38,17 @@ "dependencies": { "@docusaurus/theme-common": "^3.0.1", "@hookform/error-message": "^2.0.1", - "postman-code-generators": "^1.10.1", - "postman-collection": "^4.4.0", "@reduxjs/toolkit": "^1.7.1", "clsx": "^1.1.1", "copy-text-to-clipboard": "^3.1.0", "crypto-js": "^4.1.1", - "docusaurus-plugin-openapi-docs": "^3.0.0-beta.10", + "docusaurus-plugin-openapi-docs": "^3.0.0", "docusaurus-plugin-sass": "^0.2.3", "file-saver": "^2.0.5", "lodash": "^4.17.20", "node-polyfill-webpack-plugin": "^2.0.1", + "postman-code-generators": "^1.10.1", + "postman-collection": "^4.4.0", "prism-react-renderer": "^2.3.0", "react-hook-form": "^7.43.8", "react-live": "^4.0.0",