docusaurus-plugin-openapi-docs 2.1.3 → 2.2.1
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.
- package/README.md +86 -61
- package/lib/index.d.ts +1 -1
- package/lib/index.js +16 -13
- package/lib/markdown/createRequestSchema.js +0 -6
- package/lib/markdown/createResponseSchema.js +0 -5
- package/lib/markdown/createSchema.js +40 -20
- package/lib/markdown/createSchema.test.js +1 -0
- package/lib/markdown/createStatusCodes.js +1 -1
- package/lib/markdown/utils.d.ts +3 -0
- package/lib/markdown/utils.js +22 -1
- package/lib/openapi/openapi.js +38 -33
- package/lib/openapi/openapi.test.js +2 -0
- package/lib/openapi/types.d.ts +1 -0
- package/lib/options.js +3 -0
- package/lib/sidebars/index.js +30 -11
- package/lib/types.d.ts +4 -1
- package/package.json +4 -4
- package/src/index.ts +24 -13
- package/src/markdown/createRequestSchema.ts +0 -6
- package/src/markdown/createResponseSchema.ts +0 -6
- package/src/markdown/createSchema.test.ts +1 -0
- package/src/markdown/createSchema.ts +46 -24
- package/src/markdown/createStatusCodes.ts +1 -1
- package/src/markdown/utils.ts +22 -0
- package/src/openapi/__fixtures__/examples/openapi.yaml +7 -0
- package/src/openapi/openapi.test.ts +4 -0
- package/src/openapi/openapi.ts +43 -33
- package/src/openapi/types.ts +1 -0
- package/src/openapi-to-postmanv2.d.ts +1 -1
- package/src/options.ts +3 -0
- package/src/postman-collection.d.ts +1 -1
- package/src/sidebars/index.ts +55 -27
- package/src/types.ts +4 -1
package/README.md
CHANGED
|
@@ -6,23 +6,33 @@
|
|
|
6
6
|
|
|
7
7
|
<div align="center">
|
|
8
8
|
|
|
9
|
-
OpenAPI plugin for generating API reference docs in Docusaurus
|
|
9
|
+
OpenAPI plugin for generating API reference docs in Docusaurus v3.
|
|
10
|
+
|
|
11
|
+
<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" />
|
|
12
|
+
<br/><br/>
|
|
13
|
+
|
|
14
|
+
[](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)
|
|
15
|
+
<br/>
|
|
16
|
+
[](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)
|
|
17
|
+
<br />
|
|
10
18
|
|
|
11
19
|
</div>
|
|
12
20
|
|
|
13
21
|
<p align="center">
|
|
14
22
|
|
|
15
|
-
<img
|
|
23
|
+
<img src="https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/assets/9343811/d4e75f15-7daf-48d2-a772-a0c49aa25d26" width="900" />
|
|
16
24
|
|
|
17
25
|
</p>
|
|
18
26
|
|
|
27
|
+
---
|
|
28
|
+
|
|
19
29
|
## Overview
|
|
20
30
|
|
|
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
|
|
31
|
+
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.
|
|
22
32
|
|
|
23
33
|
Key Features:
|
|
24
34
|
|
|
25
|
-
- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.
|
|
35
|
+
- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
|
|
26
36
|
- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
|
|
27
37
|
- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
|
|
28
38
|
- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
|
|
@@ -31,16 +41,16 @@ Key Features:
|
|
|
31
41
|
|
|
32
42
|
| Docusaurus OpenAPI Docs | Docusaurus |
|
|
33
43
|
| ----------------------- | --------------- |
|
|
34
|
-
| 3.0.
|
|
35
|
-
| 2.
|
|
44
|
+
| 3.0.1 (current) | `3.0.1 - 3.4.0` |
|
|
45
|
+
| 2.2.1 (legacy) | `2.4.1 - 2.4.3` |
|
|
36
46
|
| 1.7.3 (legacy) | `2.0.1 - 2.2.0` |
|
|
37
47
|
|
|
38
48
|
## Bootstrapping from Template (new Docusaurus site)
|
|
39
49
|
|
|
40
|
-
Run the following to bootstrap a Docsaurus
|
|
50
|
+
Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
|
|
41
51
|
|
|
42
52
|
```bash
|
|
43
|
-
npx create-docusaurus@
|
|
53
|
+
npx create-docusaurus@3.4.0 my-website --package-manager yarn
|
|
44
54
|
```
|
|
45
55
|
|
|
46
56
|
> When prompted to select a template choose `Git repository`.
|
|
@@ -51,57 +61,59 @@ Template Repository URL:
|
|
|
51
61
|
https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
|
|
52
62
|
```
|
|
53
63
|
|
|
54
|
-
> When asked how the template repo should be cloned choose "copy"
|
|
64
|
+
> When asked how the template repo should be cloned choose "copy".
|
|
55
65
|
|
|
56
66
|
```bash
|
|
57
67
|
cd my-website
|
|
58
68
|
yarn start
|
|
59
69
|
```
|
|
60
70
|
|
|
71
|
+
If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API!
|
|
72
|
+
|
|
61
73
|
## Installation (existing Docusaurus site)
|
|
62
74
|
|
|
63
|
-
|
|
75
|
+
> 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.
|
|
76
|
+
|
|
77
|
+
### Plugin
|
|
64
78
|
|
|
65
79
|
```bash
|
|
66
80
|
yarn add docusaurus-plugin-openapi-docs
|
|
67
81
|
```
|
|
68
82
|
|
|
69
|
-
Theme
|
|
83
|
+
### Theme
|
|
70
84
|
|
|
71
85
|
```bash
|
|
72
86
|
yarn add docusaurus-theme-openapi-docs
|
|
73
87
|
```
|
|
74
88
|
|
|
75
|
-
## Configuring `docusaurus.config.
|
|
89
|
+
## Configuring `docusaurus.config.ts` (Plugin and theme usage)
|
|
76
90
|
|
|
77
|
-
Here is an example of properly configuring `docusaurus.config.
|
|
91
|
+
Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
|
|
78
92
|
|
|
79
|
-
|
|
80
|
-
|
|
93
|
+
> Note: Instructions may differ slightly for sites that haven't migrated to typescript.
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
// docusaurus.config.ts
|
|
97
|
+
// note that parts of the complete config were left out for brevity
|
|
98
|
+
import type * as Preset from "@docusaurus/preset-classic";
|
|
99
|
+
import type { Config } from "@docusaurus/types";
|
|
100
|
+
import type * as Plugin from "@docusaurus/types/src/plugin";
|
|
101
|
+
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
|
|
81
102
|
|
|
82
103
|
{
|
|
83
104
|
presets: [
|
|
84
105
|
[
|
|
85
106
|
"classic",
|
|
86
|
-
|
|
87
|
-
({
|
|
107
|
+
{
|
|
88
108
|
docs: {
|
|
89
|
-
sidebarPath:
|
|
90
|
-
|
|
91
|
-
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
|
|
92
|
-
docLayoutComponent: "@theme/DocPage",
|
|
93
|
-
docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
|
|
94
|
-
},
|
|
95
|
-
blog: {
|
|
96
|
-
showReadingTime: true,
|
|
97
|
-
editUrl:
|
|
98
|
-
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
|
|
109
|
+
sidebarPath: "./sidebars.ts",
|
|
110
|
+
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
|
|
99
111
|
},
|
|
100
112
|
theme: {
|
|
101
|
-
customCss:
|
|
102
|
-
}
|
|
103
|
-
}
|
|
104
|
-
]
|
|
113
|
+
customCss: "./src/css/custom.css",
|
|
114
|
+
},
|
|
115
|
+
} satisfies Preset.Options,
|
|
116
|
+
],
|
|
105
117
|
],
|
|
106
118
|
|
|
107
119
|
plugins: [
|
|
@@ -109,19 +121,15 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu
|
|
|
109
121
|
'docusaurus-plugin-openapi-docs',
|
|
110
122
|
{
|
|
111
123
|
id: "api", // plugin id
|
|
112
|
-
docsPluginId: "classic", //
|
|
124
|
+
docsPluginId: "classic", // configured for preset-classic
|
|
113
125
|
config: {
|
|
114
|
-
petstore: {
|
|
115
|
-
specPath: "examples/petstore.yaml",
|
|
116
|
-
outputDir: "
|
|
117
|
-
sidebarOptions: {
|
|
118
|
-
groupPathsBy: "tag",
|
|
126
|
+
petstore: {
|
|
127
|
+
specPath: "examples/petstore.yaml",
|
|
128
|
+
outputDir: "docs/petstore",
|
|
129
|
+
sidebarOptions: {
|
|
130
|
+
groupPathsBy: "tag",
|
|
119
131
|
},
|
|
120
|
-
},
|
|
121
|
-
burgers: {
|
|
122
|
-
specPath: "examples/food/burgers/openapi.yaml",
|
|
123
|
-
outputDir: "api/food/burgers",
|
|
124
|
-
}
|
|
132
|
+
} satisfies OpenApiPlugin.Options,
|
|
125
133
|
}
|
|
126
134
|
},
|
|
127
135
|
]
|
|
@@ -136,10 +144,11 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu
|
|
|
136
144
|
|
|
137
145
|
The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
|
|
138
146
|
|
|
139
|
-
| Name | Type | Default
|
|
140
|
-
| -------------- | -------- |
|
|
141
|
-
| `id` | `string` | `null`
|
|
142
|
-
| `
|
|
147
|
+
| Name | Type | Default | Description |
|
|
148
|
+
| -------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
149
|
+
| `id` | `string` | `null` | A unique plugin ID. |
|
|
150
|
+
| `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`). |
|
|
151
|
+
| `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"). |
|
|
143
152
|
|
|
144
153
|
### config
|
|
145
154
|
|
|
@@ -148,7 +157,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
|
|
|
148
157
|
| Name | Type | Default | Description |
|
|
149
158
|
| -------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
150
159
|
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
|
|
151
|
-
| `ouputDir` | `string` | `null` | Desired output path for generated MDX files.
|
|
160
|
+
| `ouputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
|
|
152
161
|
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
|
|
153
162
|
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
|
|
154
163
|
| `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
|
|
|
166
175
|
|
|
167
176
|
| Name | Type | Default | Description |
|
|
168
177
|
| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
-
| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`.
|
|
178
|
+
| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. |
|
|
170
179
|
| `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. |
|
|
171
180
|
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
|
|
172
181
|
| `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
|
|
|
189
198
|
|
|
190
199
|
`markdownGenerators` can be configured with the following options:
|
|
191
200
|
|
|
192
|
-
| Name
|
|
193
|
-
|
|
|
194
|
-
| `createApiPageMD`
|
|
195
|
-
| `createInfoPageMD`
|
|
196
|
-
| `createTagPageMD`
|
|
201
|
+
| Name | Type | Default | Description |
|
|
202
|
+
| -------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
203
|
+
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
|
|
204
|
+
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
|
|
205
|
+
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
|
|
206
|
+
| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
|
|
197
207
|
|
|
198
208
|
## CLI Usage
|
|
199
209
|
|
|
@@ -214,11 +224,12 @@ Commands:
|
|
|
214
224
|
write-translations [options] [siteDir] Extract required translations of your site.
|
|
215
225
|
write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content.
|
|
216
226
|
docs:version <version> Tag a new docs version
|
|
217
|
-
gen-api-docs <id>
|
|
218
|
-
gen-api-docs:version <id:version>
|
|
219
|
-
clean-api-docs <id> Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
|
|
220
|
-
clean-api-docs:version <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
|
|
227
|
+
gen-api-docs [options] <id> Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
|
|
228
|
+
gen-api-docs:version [options] <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if
|
|
221
229
|
enabled).
|
|
230
|
+
clean-api-docs [options] <id> Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
|
|
231
|
+
clean-api-docs:version [options] <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts
|
|
232
|
+
(if enabled)
|
|
222
233
|
```
|
|
223
234
|
|
|
224
235
|
### Generating OpenAPI Docs
|
|
@@ -240,10 +251,10 @@ yarn docusaurus gen-api-docs <id>
|
|
|
240
251
|
Example:
|
|
241
252
|
|
|
242
253
|
```bash
|
|
243
|
-
yarn docusaurus gen-api-docs
|
|
254
|
+
yarn docusaurus gen-api-docs petstore
|
|
244
255
|
```
|
|
245
256
|
|
|
246
|
-
> The example above will only generate API docs relative to `
|
|
257
|
+
> The example above will only generate API docs relative to `petstore`.
|
|
247
258
|
|
|
248
259
|
### Cleaning API Docs
|
|
249
260
|
|
|
@@ -262,7 +273,7 @@ yarn docusaurus clean-api-docs <id>
|
|
|
262
273
|
Example:
|
|
263
274
|
|
|
264
275
|
```bash
|
|
265
|
-
yarn docusaurus clean-api-docs
|
|
276
|
+
yarn docusaurus clean-api-docs petstore
|
|
266
277
|
```
|
|
267
278
|
|
|
268
279
|
> The example above will remove all API docs relative to `burgers`.
|
|
@@ -299,6 +310,20 @@ yarn build-packages
|
|
|
299
310
|
yarn watch:demo
|
|
300
311
|
```
|
|
301
312
|
|
|
313
|
+
## Credits
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
For more insight into why we decided to completely fork see [#47](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/47)
|
|
318
|
+
|
|
319
|
+
## Contributors
|
|
320
|
+
|
|
321
|
+
<a href="https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/graphs/contributors">
|
|
322
|
+
<img src="https://contrib.rocks/image?repo=PaloAltoNetworks/docusaurus-openapi-docs" />
|
|
323
|
+
</a>
|
|
324
|
+
|
|
302
325
|
## Support
|
|
303
326
|
|
|
304
|
-
|
|
327
|
+
See [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for our support agreement and guidelines.
|
|
328
|
+
|
|
329
|
+
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).
|
package/lib/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { LoadContext, Plugin } from "@docusaurus/types";
|
|
2
2
|
import type { PluginOptions, LoadedContent } from "./types";
|
|
3
3
|
export declare function isURL(str: string): boolean;
|
|
4
|
-
export declare function getDocsPluginConfig(presetsPlugins: any[], pluginId: string): Object | undefined;
|
|
4
|
+
export declare function getDocsPluginConfig(presetsPlugins: any[], plugin: string, pluginId: string): Object | undefined;
|
|
5
5
|
declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
|
|
6
6
|
declare namespace pluginOpenAPIDocs {
|
|
7
7
|
var validateOptions: ({ options, validate }: any) => any;
|
package/lib/index.js
CHANGED
|
@@ -24,7 +24,7 @@ function isURL(str) {
|
|
|
24
24
|
return /^(https?:)\/\//m.test(str);
|
|
25
25
|
}
|
|
26
26
|
exports.isURL = isURL;
|
|
27
|
-
function getDocsPluginConfig(presetsPlugins, pluginId) {
|
|
27
|
+
function getDocsPluginConfig(presetsPlugins, plugin, pluginId) {
|
|
28
28
|
// eslint-disable-next-line array-callback-return
|
|
29
29
|
const filteredConfig = presetsPlugins.filter((data) => {
|
|
30
30
|
// Search presets
|
|
@@ -33,8 +33,7 @@ function getDocsPluginConfig(presetsPlugins, pluginId) {
|
|
|
33
33
|
return data[1];
|
|
34
34
|
}
|
|
35
35
|
// Search plugin-content-docs instances
|
|
36
|
-
if (typeof data[0] === "string" &&
|
|
37
|
-
data[0] === "@docusaurus/plugin-content-docs") {
|
|
36
|
+
if (typeof data[0] === "string" && data[0] === plugin) {
|
|
38
37
|
const configPluginId = data[1].id ? data[1].id : "default";
|
|
39
38
|
if (configPluginId === pluginId) {
|
|
40
39
|
return data[1];
|
|
@@ -48,7 +47,7 @@ function getDocsPluginConfig(presetsPlugins, pluginId) {
|
|
|
48
47
|
return filteredConfig[1].docs;
|
|
49
48
|
}
|
|
50
49
|
// Search plugin-content-docs instances
|
|
51
|
-
if (filteredConfig[0] ===
|
|
50
|
+
if (filteredConfig[0] === plugin) {
|
|
52
51
|
const configPluginId = filteredConfig[1].id
|
|
53
52
|
? filteredConfig[1].id
|
|
54
53
|
: "default";
|
|
@@ -67,23 +66,23 @@ function getPluginInstances(plugins) {
|
|
|
67
66
|
return plugins.filter((data) => data[0] === "docusaurus-plugin-openapi-docs");
|
|
68
67
|
}
|
|
69
68
|
function pluginOpenAPIDocs(context, options) {
|
|
70
|
-
const { config, docsPluginId } = options;
|
|
69
|
+
const { config, docsPlugin = "@docusaurus/plugin-content-docs", docsPluginId, } = options;
|
|
71
70
|
const { siteDir, siteConfig } = context;
|
|
72
71
|
// Get routeBasePath and path from plugin-content-docs or preset
|
|
73
72
|
const presets = siteConfig.presets;
|
|
74
73
|
const plugins = siteConfig.plugins;
|
|
75
74
|
const presetsPlugins = presets.concat(plugins);
|
|
76
|
-
let docData = getDocsPluginConfig(presetsPlugins, docsPluginId);
|
|
75
|
+
let docData = getDocsPluginConfig(presetsPlugins, docsPlugin, docsPluginId);
|
|
77
76
|
let docRouteBasePath = docData ? docData.routeBasePath : undefined;
|
|
78
77
|
let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
|
|
79
78
|
async function generateApiDocs(options, pluginId) {
|
|
80
79
|
var _a, _b, _c, _d;
|
|
81
|
-
let { specPath, outputDir, template, markdownGenerators, downloadUrl, sidebarOptions, } = options;
|
|
80
|
+
let { specPath, outputDir, template, markdownGenerators, downloadUrl, sidebarOptions, disableCompression, } = options;
|
|
82
81
|
// Remove trailing slash before proceeding
|
|
83
82
|
outputDir = outputDir.replace(/\/$/, "");
|
|
84
83
|
// Override docPath if pluginId provided
|
|
85
84
|
if (pluginId) {
|
|
86
|
-
docData = getDocsPluginConfig(presetsPlugins, pluginId);
|
|
85
|
+
docData = getDocsPluginConfig(presetsPlugins, docsPlugin, pluginId);
|
|
87
86
|
docRouteBasePath = docData ? docData.routeBasePath : undefined;
|
|
88
87
|
docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
|
|
89
88
|
}
|
|
@@ -219,7 +218,7 @@ custom_edit_url: null
|
|
|
219
218
|
};
|
|
220
219
|
loadedApi.map(async (item) => {
|
|
221
220
|
if (item.type === "info") {
|
|
222
|
-
if (downloadUrl
|
|
221
|
+
if (downloadUrl) {
|
|
223
222
|
item.downloadUrl = downloadUrl;
|
|
224
223
|
}
|
|
225
224
|
}
|
|
@@ -233,9 +232,11 @@ custom_edit_url: null
|
|
|
233
232
|
// const deserialize = (s: any) => {
|
|
234
233
|
// return zlib.inflateSync(Buffer.from(s, "base64")).toString();
|
|
235
234
|
// };
|
|
236
|
-
|
|
237
|
-
.
|
|
238
|
-
.
|
|
235
|
+
disableCompression === true
|
|
236
|
+
? (item.json = JSON.stringify(item.api))
|
|
237
|
+
: (item.json = zlib_1.default
|
|
238
|
+
.deflateSync(JSON.stringify(item.api))
|
|
239
|
+
.toString("base64"));
|
|
239
240
|
let infoBasePath = `${outputDir}/${item.infoId}`;
|
|
240
241
|
if (docRouteBasePath) {
|
|
241
242
|
infoBasePath = `${docRouteBasePath}/${outputDir
|
|
@@ -335,7 +336,7 @@ custom_edit_url: null
|
|
|
335
336
|
cwd: path_1.default.resolve(apiDir, "schemas"),
|
|
336
337
|
deep: 1,
|
|
337
338
|
});
|
|
338
|
-
const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {
|
|
339
|
+
const sidebarFile = await (0, utils_1.Globby)(["sidebar.{js,ts}"], {
|
|
339
340
|
cwd: path_1.default.resolve(apiDir),
|
|
340
341
|
deep: 1,
|
|
341
342
|
});
|
|
@@ -371,6 +372,7 @@ custom_edit_url: null
|
|
|
371
372
|
version: version,
|
|
372
373
|
label: metadata.label,
|
|
373
374
|
baseUrl: metadata.baseUrl,
|
|
375
|
+
downloadUrl: metadata.downloadUrl,
|
|
374
376
|
});
|
|
375
377
|
}
|
|
376
378
|
const versionsJson = JSON.stringify(versionsArray, null, 2);
|
|
@@ -490,6 +492,7 @@ custom_edit_url: null
|
|
|
490
492
|
delete parentConfig.version;
|
|
491
493
|
delete parentConfig.label;
|
|
492
494
|
delete parentConfig.baseUrl;
|
|
495
|
+
delete parentConfig.downloadUrl;
|
|
493
496
|
// TODO: handle when no versions are defined by version command is passed
|
|
494
497
|
if (versionId === "all") {
|
|
495
498
|
if (versions[id]) {
|
|
@@ -88,12 +88,6 @@ function createRequestSchema({ title, body, ...rest }) {
|
|
|
88
88
|
if (firstBody === undefined) {
|
|
89
89
|
return undefined;
|
|
90
90
|
}
|
|
91
|
-
// we don't show the table if there is no properties to show
|
|
92
|
-
if (firstBody.properties !== undefined) {
|
|
93
|
-
if (Object.keys(firstBody.properties).length === 0) {
|
|
94
|
-
return undefined;
|
|
95
|
-
}
|
|
96
|
-
}
|
|
97
91
|
return (0, utils_1.create)("MimeTabs", {
|
|
98
92
|
className: "openapi-tabs__mime",
|
|
99
93
|
children: [
|
|
@@ -36,11 +36,6 @@ function createResponseSchema({ title, body, ...rest }) {
|
|
|
36
36
|
responseExamples === undefined) {
|
|
37
37
|
return undefined;
|
|
38
38
|
}
|
|
39
|
-
if ((firstBody === null || firstBody === void 0 ? void 0 : firstBody.properties) !== undefined) {
|
|
40
|
-
if (Object.keys(firstBody === null || firstBody === void 0 ? void 0 : firstBody.properties).length === 0) {
|
|
41
|
-
return undefined;
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
39
|
return (0, utils_1.create)("TabItem", {
|
|
45
40
|
label: `${mimeType}`,
|
|
46
41
|
value: `${mimeType}`,
|
|
@@ -116,6 +116,16 @@ function createAnyOneOf(schema) {
|
|
|
116
116
|
*/
|
|
117
117
|
function createProperties(schema) {
|
|
118
118
|
const discriminator = schema.discriminator;
|
|
119
|
+
if (Object.keys(schema.properties).length === 0) {
|
|
120
|
+
return (0, utils_1.create)("SchemaItem", {
|
|
121
|
+
collapsible: false,
|
|
122
|
+
name: "",
|
|
123
|
+
required: false,
|
|
124
|
+
schemaName: "object",
|
|
125
|
+
qualifierMessage: undefined,
|
|
126
|
+
schema: {},
|
|
127
|
+
});
|
|
128
|
+
}
|
|
119
129
|
return Object.entries(schema.properties).map(([key, val]) => {
|
|
120
130
|
return createEdges({
|
|
121
131
|
name: key,
|
|
@@ -483,6 +493,16 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
|
|
|
483
493
|
*/
|
|
484
494
|
function createEdges({ name, schema, required, discriminator, }) {
|
|
485
495
|
var _a, _b, _c, _d;
|
|
496
|
+
if (SCHEMA_TYPE === "request") {
|
|
497
|
+
if (schema.readOnly && schema.readOnly === true) {
|
|
498
|
+
return undefined;
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
if (SCHEMA_TYPE === "response") {
|
|
502
|
+
if (schema.writeOnly && schema.writeOnly === true) {
|
|
503
|
+
return undefined;
|
|
504
|
+
}
|
|
505
|
+
}
|
|
486
506
|
const schemaName = (0, schema_1.getSchemaName)(schema);
|
|
487
507
|
if (discriminator !== undefined && discriminator.propertyName === name) {
|
|
488
508
|
return createPropertyDiscriminator(name, "string", schema, discriminator, required);
|
|
@@ -492,6 +512,16 @@ function createEdges({ name, schema, required, discriminator, }) {
|
|
|
492
512
|
}
|
|
493
513
|
if (schema.allOf !== undefined) {
|
|
494
514
|
const { mergedSchemas } = mergeAllOf(schema.allOf);
|
|
515
|
+
if (SCHEMA_TYPE === "request") {
|
|
516
|
+
if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
|
|
517
|
+
return undefined;
|
|
518
|
+
}
|
|
519
|
+
}
|
|
520
|
+
if (SCHEMA_TYPE === "response") {
|
|
521
|
+
if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
|
|
522
|
+
return undefined;
|
|
523
|
+
}
|
|
524
|
+
}
|
|
495
525
|
const mergedSchemaName = (0, schema_1.getSchemaName)(mergedSchemas);
|
|
496
526
|
if (mergedSchemas.oneOf !== undefined ||
|
|
497
527
|
mergedSchemas.anyOf !== undefined) {
|
|
@@ -507,16 +537,6 @@ function createEdges({ name, schema, required, discriminator, }) {
|
|
|
507
537
|
if (((_a = mergedSchemas.items) === null || _a === void 0 ? void 0 : _a.properties) !== undefined) {
|
|
508
538
|
return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
|
|
509
539
|
}
|
|
510
|
-
if (SCHEMA_TYPE === "request") {
|
|
511
|
-
if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
|
|
512
|
-
return undefined;
|
|
513
|
-
}
|
|
514
|
-
}
|
|
515
|
-
if (SCHEMA_TYPE === "response") {
|
|
516
|
-
if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
|
|
517
|
-
return undefined;
|
|
518
|
-
}
|
|
519
|
-
}
|
|
520
540
|
return (0, utils_1.create)("SchemaItem", {
|
|
521
541
|
collapsible: false,
|
|
522
542
|
name,
|
|
@@ -539,16 +559,6 @@ function createEdges({ name, schema, required, discriminator, }) {
|
|
|
539
559
|
if (((_c = schema.items) === null || _c === void 0 ? void 0 : _c.anyOf) !== undefined || ((_d = schema.items) === null || _d === void 0 ? void 0 : _d.oneOf) !== undefined) {
|
|
540
560
|
return createDetailsNode(name, schemaName, schema, required, schema.nullable);
|
|
541
561
|
}
|
|
542
|
-
if (SCHEMA_TYPE === "request") {
|
|
543
|
-
if (schema.readOnly && schema.readOnly === true) {
|
|
544
|
-
return undefined;
|
|
545
|
-
}
|
|
546
|
-
}
|
|
547
|
-
if (SCHEMA_TYPE === "response") {
|
|
548
|
-
if (schema.writeOnly && schema.writeOnly === true) {
|
|
549
|
-
return undefined;
|
|
550
|
-
}
|
|
551
|
-
}
|
|
552
562
|
// primitives and array of non-objects
|
|
553
563
|
return (0, utils_1.create)("SchemaItem", {
|
|
554
564
|
collapsible: false,
|
|
@@ -564,6 +574,16 @@ function createEdges({ name, schema, required, discriminator, }) {
|
|
|
564
574
|
*/
|
|
565
575
|
function createNodes(schema, schemaType) {
|
|
566
576
|
SCHEMA_TYPE = schemaType;
|
|
577
|
+
if (SCHEMA_TYPE === "request") {
|
|
578
|
+
if (schema.readOnly && schema.readOnly === true) {
|
|
579
|
+
return undefined;
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
if (SCHEMA_TYPE === "response") {
|
|
583
|
+
if (schema.writeOnly && schema.writeOnly === true) {
|
|
584
|
+
return undefined;
|
|
585
|
+
}
|
|
586
|
+
}
|
|
567
587
|
const nodes = [];
|
|
568
588
|
// if (schema.discriminator !== undefined) {
|
|
569
589
|
// return createDiscriminator(schema);
|
|
@@ -275,7 +275,7 @@ function createStatusCodes({ label, id, responses }) {
|
|
|
275
275
|
responseHeaders &&
|
|
276
276
|
(0, createDetails_1.createDetails)({
|
|
277
277
|
className: "openapi-markdown__details",
|
|
278
|
-
"data-
|
|
278
|
+
"data-collapsed": true,
|
|
279
279
|
open: false,
|
|
280
280
|
style: { textAlign: "left", marginBottom: "1rem" },
|
|
281
281
|
children: [
|
package/lib/markdown/utils.d.ts
CHANGED
|
@@ -8,3 +8,6 @@ export declare function render(children: Children): string;
|
|
|
8
8
|
export declare const lessThan: RegExp;
|
|
9
9
|
export declare const greaterThan: RegExp;
|
|
10
10
|
export declare const codeFence: RegExp;
|
|
11
|
+
export declare const curlyBrackets: RegExp;
|
|
12
|
+
export declare const codeBlock: RegExp;
|
|
13
|
+
export declare function clean(value: string | undefined): string;
|
package/lib/markdown/utils.js
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* LICENSE file in the root directory of this source tree.
|
|
7
7
|
* ========================================================================== */
|
|
8
8
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
9
|
-
exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
|
|
9
|
+
exports.clean = exports.codeBlock = exports.curlyBrackets = exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
|
|
10
10
|
function create(tag, props) {
|
|
11
11
|
const { children, ...rest } = props;
|
|
12
12
|
let propString = "";
|
|
@@ -38,3 +38,24 @@ exports.render = render;
|
|
|
38
38
|
exports.lessThan = /<(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
|
|
39
39
|
exports.greaterThan = /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
|
|
40
40
|
exports.codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
|
|
41
|
+
exports.curlyBrackets = /([{}])/g;
|
|
42
|
+
exports.codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
|
|
43
|
+
function clean(value) {
|
|
44
|
+
if (!value) {
|
|
45
|
+
return "";
|
|
46
|
+
}
|
|
47
|
+
let sections = value.split(exports.codeBlock);
|
|
48
|
+
for (let sectionIndex in sections) {
|
|
49
|
+
if (!sections[sectionIndex].startsWith("`")) {
|
|
50
|
+
sections[sectionIndex] = sections[sectionIndex]
|
|
51
|
+
.replace(exports.lessThan, "<")
|
|
52
|
+
.replace(exports.greaterThan, ">")
|
|
53
|
+
.replace(exports.codeFence, function (match) {
|
|
54
|
+
return match.replace(/\\>/g, ">");
|
|
55
|
+
})
|
|
56
|
+
.replace(exports.curlyBrackets, "\\$1");
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return sections.join("");
|
|
60
|
+
}
|
|
61
|
+
exports.clean = clean;
|