Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/paloaltonetworks/docusaurus-openapi-docs
🦝 OpenAPI plugin for generating API reference docs in Docusaurus v3.
https://github.com/paloaltonetworks/docusaurus-openapi-docs
docusaurus docusaurus-plugin docusaurus-theme docusaurus2 openapi react
Last synced: 7 days ago
JSON representation
🦝 OpenAPI plugin for generating API reference docs in Docusaurus v3.
- Host: GitHub
- URL: https://github.com/paloaltonetworks/docusaurus-openapi-docs
- Owner: PaloAltoNetworks
- License: mit
- Created: 2022-02-16T16:06:40.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T17:54:20.000Z (2 months ago)
- Last Synced: 2024-10-25T17:18:27.819Z (2 months ago)
- Topics: docusaurus, docusaurus-plugin, docusaurus-theme, docusaurus2, openapi, react
- Language: TypeScript
- Homepage: https://docusaurus-openapi.tryingpan.dev
- Size: 7.77 MB
- Stars: 693
- Watchers: 9
- Forks: 233
- Open Issues: 71
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
Docusaurus OpenAPI Doc Generator
OpenAPI plugin for generating API reference docs in Docusaurus v3 (compatible with [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556).
[](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs)
[](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/actions/workflows/validate.yaml) [](https://github.com/prettier/prettier) [](https://www.cypress.io/) [](https://github.com/facebook/jest) [](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/CONTRIBUTING.md#pull-requests)
---
## 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 when combined with the `docusaurus-theme-openapi-docs` theme.
Key Features:
- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
## Compatibility Matrix
| Docusaurus OpenAPI Docs | Docusaurus |
| ----------------------- | --------------- |
| 4.x.x (current) | `3.5.0 - 3.6.x` |
| 3.0.x (end-of-support) | `3.0.1 - 3.4.0` |
| 2.2.3 (legacy) | `2.4.1 - 2.4.3` |
| 1.7.3 (end-of-support) | `2.0.1 - 2.2.0` |
## Bootstrapping from Template (new Docusaurus site)
Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
```bash
npx [email protected] 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".
```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)
> 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
```bash
yarn add docusaurus-theme-openapi-docs
```
## Configuring `docusaurus.config.ts` (Plugin and theme usage)
Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
> 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",
{
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
}
```
> 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`.
## 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. |
| `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
`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 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
`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. |
| `sidebarGenerators` | `object` | `null` | Optional: Customize sidebar rendering with callback functions. |
> 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. |
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification for versioned. |
> 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` |
### sidebarGenerators
`sidebarGenerators` can be configured with the following options:
| Name | Type | Default | Description |
| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createDocItem` | `function` | `null` | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.
**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
## CLI Usage
```bash
Usage: docusaurus [options]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] [siteDir] Build website.
swizzle [options] [themeName] [componentName] [siteDir] Wraps or ejects the original theme files into website folder for customization.
deploy [options] [siteDir] Deploy website to GitHub pages.
start [options] [siteDir] Start the development server.
serve [options] [siteDir] Serve website locally.
clear [siteDir] Remove build artifacts.
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 [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
To generate all OpenAPI docs, run the following command from the root directory of your project:
```bash
yarn docusaurus gen-api-docs all
```
> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
You may also generate OpenAPI docs for a single path or OAS by specifying the unique `id`:
```bash
yarn docusaurus gen-api-docs
```
Example:
```bash
yarn docusaurus gen-api-docs petstore
```
> The example above will only generate API docs relative to `petstore`.
If you have multiple versions of the same API, `gen-api-docs` only generates the latest. To generate all versions, use the `--all-versions` flag.
Example:
```bash
yarn docusaurus gen-api-docs all --all-versions
```
> This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
### Cleaning API Docs
To clean/remove all API Docs, run the following command from the root directory of your project:
```bash
yarn docusaurus clean-api-docs all
```
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
```
Example:
```bash
yarn docusaurus clean-api-docs petstore
```
> The example above will remove all API docs relative to `burgers`.
If you have multiple versions of the same API, `clean-api-docs` only cleans the latest. To clean all versions, use the `--all-versions` flag.
Example:
```bash
yarn docusaurus clean-api-docs all --all-versions
```
> This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
### Versioning OpenAPI docs
To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
```bash
yarn docusaurus gen-api-docs:version :all
```
Example:
```bash
yarn docusaurus gen-api-docs:version petstore:all
```
> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
## Developer Quick Start
> Looking to make a contribution? Make sure to checkout out our contributing guide.
After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
```bash
git clone https://github.com//docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demo
```
## Credits
Special thanks to [@bourdakos1](https://github.com/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
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).