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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +84 -7
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -20,6 +20,13 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2.
20
20
 
21
21
  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.
22
22
 
23
+ Key Features:
24
+
25
+ - **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
26
+ - **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
27
+ - **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
28
+ - **Capable:** Supports single, multi and _even micro_ OpenAPI specs.
29
+
23
30
  ## Installation
24
31
 
25
32
  Plugin:
@@ -71,7 +78,6 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
71
78
  ],
72
79
 
73
80
  plugins: [
74
- [
75
81
  'docusaurus-plugin-openapi-docs',
76
82
  {
77
83
  id: "apiDocs",
@@ -107,18 +113,33 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
107
113
  | `ouputDir` | `string` | `null` | Desired output path for generated MDX files. |
108
114
  | `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
109
115
  | `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
116
+ | `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
117
+ | `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
118
+ | `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
119
+ | `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
110
120
 
111
121
  `sidebarOptions` can be configured with the following options:
112
122
 
113
123
  | Name | Type | Default | Description |
114
124
  | -------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115
125
  | `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`. |
116
- | `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). |
126
+ | `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). |
117
127
  | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
118
128
  | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
119
129
  | `customProps` | `object` | `null` | Additional props for customizing a sidebar item. |
120
130
 
121
- > Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
131
+ > 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`.
132
+
133
+ `versions` can be configured with the following options:
134
+
135
+ | Name | Type | Default | Description |
136
+ | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
137
+ | `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
138
+ | `ouputDir` | `string` | `null` | Desired output path for versioned, generated MDX files. |
139
+ | `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
140
+ | `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
141
+
142
+ > All versions will automatically inherit `sidebarOptions` from the parent/base config.
122
143
 
123
144
  ## CLI Usage
124
145
 
@@ -139,9 +160,11 @@ Commands:
139
160
  write-translations [options] [siteDir] Extract required translations of your site.
140
161
  write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content.
141
162
  docs:version <version> Tag a new docs version
142
- gen-api-docs <id> Generates API Docs mdx and sidebars.
143
- clean-api-docs <id> Clears the Generated API Docs mdx and sidebars.
144
- docs:version:openapi <version> Tag a new docs version (openapi)
163
+ gen-api-docs <id> Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
164
+ gen-api-docs:version <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
165
+ clean-api-docs <id> Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
166
+ clean-api-docs:version <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
167
+ enabled).
145
168
  ```
146
169
 
147
170
  ### Generating OpenAPI Docs
@@ -190,6 +213,60 @@ yarn docusaurus clean-api-docs burgers
190
213
 
191
214
  > The example above will remove all API docs relative to `burgers`.
192
215
 
216
+ ### Versioning OpenAPI docs
217
+
218
+ To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
219
+
220
+ ```bash
221
+ yarn docusaurus gen-api-docs:version <id>:all
222
+ ```
223
+
224
+ Example:
225
+
226
+ ```bash
227
+ yarn docusaurus gen-api-docs:version petstore:all
228
+ ```
229
+
230
+ > 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.
231
+
232
+ > 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.
233
+
234
+ ## Installing from Template
235
+
236
+ Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
237
+
238
+ ```bash
239
+ npx create-docusaurus@2.0.0-beta.21 my-website --package-manager yarn
240
+ ```
241
+
242
+ > When prompted to select a template choose `Git repository`.
243
+
244
+ Template Repository URL:
245
+
246
+ ```bash
247
+ https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
248
+ ```
249
+
250
+ > When asked how the template repo should be cloned choose "copy" (unless you know better).
251
+
252
+ ````bash
253
+ cd my-website
254
+ yarn
255
+
256
+ ## Developer Quick Start
257
+
258
+ > Looking to make a contribution? Make sure to checkout out our contributing guide.
259
+
260
+ After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
261
+
262
+ ```bash
263
+ git clone https://github.com/<your account>/docusaurus-openapi-docs.git
264
+ cd docusaurus-openapi-docs
265
+ yarn
266
+ yarn build-packages
267
+ yarn watch:demo
268
+ ````
269
+
193
270
  ## Support
194
271
 
195
- Please read [SUPPORT.md](SUPPORT.md) for details on how to get support for this project.
272
+ Please read [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for details on how to get support for this project.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "docusaurus-plugin-openapi-docs",
3
3
  "description": "OpenAPI plugin for Docusaurus.",
4
- "version": "0.0.0-376",
4
+ "version": "0.0.0-378",
5
5
  "license": "MIT",
6
6
  "keywords": [
7
7
  "openapi",
@@ -62,5 +62,5 @@
62
62
  "engines": {
63
63
  "node": ">=14"
64
64
  },
65
- "gitHead": "1a772d94e5e7075dff6f522aef9aab9303a0e007"
65
+ "gitHead": "c53b459f45fdd3e45047fbddbc48a7670f6abfbd"
66
66
  }