docusaurus-plugin-openapi-docs 4.3.7 → 4.4.0
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 +19 -16
- package/lib/index.js +11 -6
- package/lib/options.js +3 -0
- package/lib/types.d.ts +3 -0
- package/package.json +2 -2
- package/src/index.ts +13 -5
- package/src/options.ts +3 -0
- package/src/types.ts +3 -0
package/README.md
CHANGED
|
@@ -155,22 +155,25 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
|
|
|
155
155
|
|
|
156
156
|
`config` can be configured with the following options:
|
|
157
157
|
|
|
158
|
-
| Name | Type | Default | Description
|
|
159
|
-
| -------------------- | --------- | ------- |
|
|
160
|
-
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.
|
|
161
|
-
| `
|
|
162
|
-
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser.
|
|
163
|
-
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template.
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
158
|
+
| Name | Type | Default | Description |
|
|
159
|
+
| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
160
|
+
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
|
|
161
|
+
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
|
|
162
|
+
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
|
|
163
|
+
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
|
|
164
|
+
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
|
|
165
|
+
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
|
|
166
|
+
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
|
|
167
|
+
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
|
|
168
|
+
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
|
|
169
|
+
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
|
|
170
|
+
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
|
|
171
|
+
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
|
|
172
|
+
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
|
|
173
|
+
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
|
|
174
|
+
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
|
|
175
|
+
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
|
|
176
|
+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
|
|
174
177
|
|
|
175
178
|
### sidebarOptions
|
|
176
179
|
|
package/lib/index.js
CHANGED
|
@@ -78,7 +78,7 @@ function pluginOpenAPIDocs(context, options) {
|
|
|
78
78
|
let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
|
|
79
79
|
async function generateApiDocs(options, pluginId) {
|
|
80
80
|
var _a, _b, _c, _d;
|
|
81
|
-
let { specPath, outputDir, template, markdownGenerators, downloadUrl, sidebarOptions, disableCompression, } = options;
|
|
81
|
+
let { specPath, outputDir, template, infoTemplate, tagTemplate, schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, disableCompression, } = options;
|
|
82
82
|
// Remove trailing slash before proceeding
|
|
83
83
|
outputDir = outputDir.replace(/\/$/, "");
|
|
84
84
|
// Override docPath if pluginId provided
|
|
@@ -163,7 +163,9 @@ show_extensions: true
|
|
|
163
163
|
|
|
164
164
|
{{{markdown}}}
|
|
165
165
|
`;
|
|
166
|
-
const infoMdTemplate =
|
|
166
|
+
const infoMdTemplate = infoTemplate
|
|
167
|
+
? fs_1.default.readFileSync(infoTemplate).toString()
|
|
168
|
+
: `---
|
|
167
169
|
id: {{{id}}}
|
|
168
170
|
title: "{{{title}}}"
|
|
169
171
|
description: "{{{frontMatter.description}}}"
|
|
@@ -181,7 +183,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
|
|
181
183
|
<DocCardList items={useCurrentSidebarCategory().items}/>
|
|
182
184
|
\`\`\`
|
|
183
185
|
`;
|
|
184
|
-
const tagMdTemplate =
|
|
186
|
+
const tagMdTemplate = tagTemplate
|
|
187
|
+
? fs_1.default.readFileSync(tagTemplate).toString()
|
|
188
|
+
: `---
|
|
185
189
|
id: {{{id}}}
|
|
186
190
|
title: "{{{frontMatter.description}}}"
|
|
187
191
|
description: "{{{frontMatter.description}}}"
|
|
@@ -197,7 +201,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
|
|
197
201
|
<DocCardList items={useCurrentSidebarCategory().items}/>
|
|
198
202
|
\`\`\`
|
|
199
203
|
`;
|
|
200
|
-
const schemaMdTemplate =
|
|
204
|
+
const schemaMdTemplate = schemaTemplate
|
|
205
|
+
? fs_1.default.readFileSync(schemaTemplate).toString()
|
|
206
|
+
: `---
|
|
201
207
|
id: {{{id}}}
|
|
202
208
|
title: "{{{title}}}"
|
|
203
209
|
description: "{{{frontMatter.description}}}"
|
|
@@ -270,11 +276,10 @@ custom_edit_url: null
|
|
|
270
276
|
}
|
|
271
277
|
}
|
|
272
278
|
}
|
|
273
|
-
// TODO: determine if we actually want/need this
|
|
274
279
|
if (item.type === "info") {
|
|
275
280
|
if (!fs_1.default.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
|
|
276
281
|
try {
|
|
277
|
-
(sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "info" // Only use utils template if set to "info"
|
|
282
|
+
(sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "info" || infoTemplate // Only use utils template if set to "info" or if infoTemplate is set
|
|
278
283
|
? fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, utils, "utf8")
|
|
279
284
|
: fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, view, "utf8");
|
|
280
285
|
console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.info.mdx"`));
|
package/lib/options.js
CHANGED
|
@@ -35,6 +35,9 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
|
|
|
35
35
|
proxy: utils_validation_1.Joi.string(),
|
|
36
36
|
outputDir: utils_validation_1.Joi.string().required(),
|
|
37
37
|
template: utils_validation_1.Joi.string(),
|
|
38
|
+
infoTemplate: utils_validation_1.Joi.string(),
|
|
39
|
+
tagTemplate: utils_validation_1.Joi.string(),
|
|
40
|
+
schemaTemplate: utils_validation_1.Joi.string(),
|
|
38
41
|
downloadUrl: utils_validation_1.Joi.string(),
|
|
39
42
|
hideSendButton: utils_validation_1.Joi.boolean(),
|
|
40
43
|
showExtensions: utils_validation_1.Joi.boolean(),
|
package/lib/types.d.ts
CHANGED
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": "4.
|
|
4
|
+
"version": "4.4.0",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"openapi",
|
|
@@ -65,5 +65,5 @@
|
|
|
65
65
|
"engines": {
|
|
66
66
|
"node": ">=14"
|
|
67
67
|
},
|
|
68
|
-
"gitHead": "
|
|
68
|
+
"gitHead": "808e4a252af8e24201e38a6ecbddb05b844891a2"
|
|
69
69
|
}
|
package/src/index.ts
CHANGED
|
@@ -117,6 +117,9 @@ export default function pluginOpenAPIDocs(
|
|
|
117
117
|
specPath,
|
|
118
118
|
outputDir,
|
|
119
119
|
template,
|
|
120
|
+
infoTemplate,
|
|
121
|
+
tagTemplate,
|
|
122
|
+
schemaTemplate,
|
|
120
123
|
markdownGenerators,
|
|
121
124
|
downloadUrl,
|
|
122
125
|
sidebarOptions,
|
|
@@ -236,7 +239,9 @@ show_extensions: true
|
|
|
236
239
|
{{{markdown}}}
|
|
237
240
|
`;
|
|
238
241
|
|
|
239
|
-
const infoMdTemplate =
|
|
242
|
+
const infoMdTemplate = infoTemplate
|
|
243
|
+
? fs.readFileSync(infoTemplate).toString()
|
|
244
|
+
: `---
|
|
240
245
|
id: {{{id}}}
|
|
241
246
|
title: "{{{title}}}"
|
|
242
247
|
description: "{{{frontMatter.description}}}"
|
|
@@ -255,7 +260,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
|
|
255
260
|
\`\`\`
|
|
256
261
|
`;
|
|
257
262
|
|
|
258
|
-
const tagMdTemplate =
|
|
263
|
+
const tagMdTemplate = tagTemplate
|
|
264
|
+
? fs.readFileSync(tagTemplate).toString()
|
|
265
|
+
: `---
|
|
259
266
|
id: {{{id}}}
|
|
260
267
|
title: "{{{frontMatter.description}}}"
|
|
261
268
|
description: "{{{frontMatter.description}}}"
|
|
@@ -272,7 +279,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
|
|
272
279
|
\`\`\`
|
|
273
280
|
`;
|
|
274
281
|
|
|
275
|
-
const schemaMdTemplate =
|
|
282
|
+
const schemaMdTemplate = schemaTemplate
|
|
283
|
+
? fs.readFileSync(schemaTemplate).toString()
|
|
284
|
+
: `---
|
|
276
285
|
id: {{{id}}}
|
|
277
286
|
title: "{{{title}}}"
|
|
278
287
|
description: "{{{frontMatter.description}}}"
|
|
@@ -371,11 +380,10 @@ custom_edit_url: null
|
|
|
371
380
|
}
|
|
372
381
|
}
|
|
373
382
|
|
|
374
|
-
// TODO: determine if we actually want/need this
|
|
375
383
|
if (item.type === "info") {
|
|
376
384
|
if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
|
|
377
385
|
try {
|
|
378
|
-
sidebarOptions?.categoryLinkSource === "info" // Only use utils template if set to "info"
|
|
386
|
+
sidebarOptions?.categoryLinkSource === "info" || infoTemplate // Only use utils template if set to "info" or if infoTemplate is set
|
|
379
387
|
? fs.writeFileSync(
|
|
380
388
|
`${outputDir}/${item.id}.info.mdx`,
|
|
381
389
|
utils,
|
package/src/options.ts
CHANGED
|
@@ -39,6 +39,9 @@ export const OptionsSchema = Joi.object({
|
|
|
39
39
|
proxy: Joi.string(),
|
|
40
40
|
outputDir: Joi.string().required(),
|
|
41
41
|
template: Joi.string(),
|
|
42
|
+
infoTemplate: Joi.string(),
|
|
43
|
+
tagTemplate: Joi.string(),
|
|
44
|
+
schemaTemplate: Joi.string(),
|
|
42
45
|
downloadUrl: Joi.string(),
|
|
43
46
|
hideSendButton: Joi.boolean(),
|
|
44
47
|
showExtensions: Joi.boolean(),
|
package/src/types.ts
CHANGED