-
Notifications
You must be signed in to change notification settings - Fork 224
/
intro.mdx
393 lines (290 loc) · 23.6 KB
/
intro.mdx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
---
sidebar_position: 1
hide_title: true
sidebar_label: Docusaurus OpenAPI Docs
title: Overview
slug: /
image: https://docusaurus-openapi.tryingpan.dev/img/docusaurus-openapi-docs-logo.svg
tags:
- documentation
- openapi
- getting started
- quickstart
---
<head>
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
</head>
<div align="center">
<img width="200" src="https://user-images.githubusercontent.com/9343811/165975569-1bc29814-884c-4931-83df-860043b625b7.svg" />
</div>
<div align="center">
OpenAPI plugin for generating API reference docs in Docusaurus v3.
<img src="https://img.shields.io/badge/dynamic/json?style=for-the-badge&logo=meta&color=blueviolet&label=Docusaurus&query=dependencies%5B%22%40docusaurus%2Fcore%22%5D&url=https%3A%2F%2Fraw.githubusercontent.com%2FPaloAltoNetworks%2Fdocusaurus-openapi-docs%2Fmain%2Fdemo%2Fpackage.json" />
<br/><br/>
[](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)
<iframe
src="https://ghbtns.com/github-btn.html?user=PaloAltoNetworks&repo=docusaurus-openapi-docs&type=star&count=true&size=large"
width={160}
height={30}
title="GitHub Stars"
/>
</div>
---
## 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.0.x (current) | `3.5.0 - 3.5.2` |
| 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` |
:::tip
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).
:::
## 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@3.5.2 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
```
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
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
```
## Configuration
## 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 [markdownGenerators](#markdowngenerators) 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. <br/><br/>The supported options are as follows: <br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). <br/><br/>`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. |
> 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.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
Example:
```javascript
petstore31: {
specPath: "examples/petstore-3.1.yaml",
proxy: "https://cors.pan.dev",
outputDir: "docs/petstore31",
sidebarOptions: {
groupPathsBy: "tag",
categoryLinkSource: "tag",
},
downloadUrl: "/petstore-3.1.yaml",
hideSendButton: false,
showSchemas: true,
markdownGenerators: { createApiPageMD: myCustomApiMdGenerator }, // customize MDX with markdown generator
} satisfies OpenApiPlugin.Options,
```
### 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.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
## CLI Usage
After you've installed and configured the plugin and theme, the CLI can be used to `generate` and `clean` API docs.
```
Usage: docusaurus <command> [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 <version> Tag a new docs version
gen-api-docs [options] <id> Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
gen-api-docs:version [options] <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if
enabled).
clean-api-docs [options] <id> Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
clean-api-docs:version [options] <id:version> 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:
:::note
This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
:::
```bash
yarn docusaurus gen-api-docs all
```
You may also generate OpenAPI docs for a single path or OAS by specifying the unique `id`:
```bash
yarn docusaurus gen-api-docs <id>
```
Example:
```bash title="generating API docs for 'petstore'"
yarn docusaurus gen-api-docs petstore
```
### 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 <id>
```
Example:
```bash title="cleaning API docs for 'petstore'"
yarn docusaurus clean-api-docs petstore
```
### Versioning OpenAPI docs
To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
```bash
yarn docusaurus gen-api-docs:version <id>:all
```
Examples:
```bash title="generate all versioned API docs for 'petstore'"
yarn docusaurus gen-api-docs:version petstore:all
```
```bash title="generate version 1.0.0 API docs for 'petstore'"
yarn docusaurus gen-api-docs:version petstore:1.0.0
```
:::tip
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.
:::
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).
## Developer Quick Start
> Looking to make a contribution? Make sure to checkout out our contributing guide.
After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
```bash
git clone https://github.com/<your account>/docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demo
```
## 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
<a href="https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/graphs/contributors">
<img src="https://contrib.rocks/image?repo=PaloAltoNetworks/docusaurus-openapi-docs" />
</a>
## 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).