docusaurus-plugin-openapi-docs 2.0.0-beta.1 → 2.0.0-beta.3

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 CHANGED
@@ -125,6 +125,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
125
125
  | `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
126
126
  | `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
127
127
  | `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel |
128
+ | `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. |
128
129
  | `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
129
130
  | `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
130
131
  | `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
@@ -133,13 +134,13 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
133
134
 
134
135
  `sidebarOptions` can be configured with the following options:
135
136
 
136
- | Name | Type | Default | Description |
137
- | -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
138
- | `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`. |
139
- | `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. |
140
- | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
141
- | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
142
- | `customProps` | `object` | `null` | Additional props for customizing a sidebar item. |
137
+ | Name | Type | Default | Description |
138
+ | -------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
+ | `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`. |
140
+ | `categoryLinkSource` | `string` | `null` | Defines what source to use for rendering category pages when grouping paths by tag. By default, pages are not created for categories, only groups that can be expanded/collapsed. <br/><br/>The supported options are as follows: <br/><br/> `auto`: Sets the category link config type to `generated-index`, building an index page with links to each page in the group.<br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description at the top of the page. <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). |
141
+ | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
142
+ | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
143
+ | `customProps` | `object` | `null` | Additional props for customizing a sidebar item. |
143
144
 
144
145
  > 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`.
145
146
 
package/lib/index.js CHANGED
@@ -152,6 +152,9 @@ proxy: {{{frontMatter.proxy}}}
152
152
  {{#frontMatter.hide_send_button}}
153
153
  hide_send_button: true
154
154
  {{/frontMatter.hide_send_button}}
155
+ {{#frontMatter.show_extensions}}
156
+ show_extensions: true
157
+ {{/frontMatter.show_extensions}}
155
158
  ---
156
159
 
157
160
  {{{markdown}}}
@@ -196,12 +199,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
196
199
  item.downloadUrl = downloadUrl;
197
200
  }
198
201
  }
199
- const markdown = item.type === "api"
200
- ? (0, markdown_1.createApiPageMD)(item)
201
- : item.type === "info"
202
- ? (0, markdown_1.createInfoPageMD)(item)
203
- : (0, markdown_1.createTagPageMD)(item);
204
- item.markdown = markdown;
205
202
  if (item.type === "api") {
206
203
  item.json = JSON.stringify(item.api);
207
204
  let infoBasePath = `${outputDir}/${item.infoId}`;
@@ -213,6 +210,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
213
210
  if (item.infoId)
214
211
  item.infoPath = infoBasePath;
215
212
  }
213
+ const markdown = item.type === "api"
214
+ ? (0, markdown_1.createApiPageMD)(item)
215
+ : item.type === "info"
216
+ ? (0, markdown_1.createInfoPageMD)(item)
217
+ : (0, markdown_1.createTagPageMD)(item);
218
+ item.markdown = markdown;
216
219
  const view = (0, mustache_1.render)(mdTemplate, item);
217
220
  const utils = (0, mustache_1.render)(infoMdTemplate, item);
218
221
  // eslint-disable-next-line testing-library/render-result-naming-convention
@@ -0,0 +1 @@
1
+ export declare function createAuthorization(infoPath: string): string[] | undefined;
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ /* ============================================================================
3
+ * Copyright (c) Palo Alto Networks
4
+ *
5
+ * This source code is licensed under the MIT license found in the
6
+ * LICENSE file in the root directory of this source tree.
7
+ * ========================================================================== */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.createAuthorization = void 0;
10
+ const utils_1 = require("./utils");
11
+ function createAuthorization(infoPath) {
12
+ if (!infoPath)
13
+ return undefined;
14
+ return [(0, utils_1.create)("SecuritySchemes", { infoPath: infoPath }), "\n\n"];
15
+ }
16
+ exports.createAuthorization = createAuthorization;
@@ -26,7 +26,8 @@ function createParamsDetails({ parameters, type }) {
26
26
  children: [
27
27
  (0, createDetailsSummary_1.createDetailsSummary)({
28
28
  children: [
29
- (0, utils_1.create)("strong", {
29
+ (0, utils_1.create)("h3", {
30
+ className: "openapi-markdown__details-summary-header-params",
30
31
  children: `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`,
31
32
  }),
32
33
  ],
@@ -0,0 +1 @@
1
+ export declare function createRequestHeader(header: string): string;
@@ -0,0 +1,13 @@
1
+ "use strict";
2
+ /* ============================================================================
3
+ * Copyright (c) Palo Alto Networks
4
+ *
5
+ * This source code is licensed under the MIT license found in the
6
+ * LICENSE file in the root directory of this source tree.
7
+ * ========================================================================== */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.createRequestHeader = void 0;
10
+ function createRequestHeader(header) {
11
+ return `## ${header}\n\n`;
12
+ }
13
+ exports.createRequestHeader = createRequestHeader;
@@ -5,8 +5,12 @@
5
5
  * This source code is licensed under the MIT license found in the
6
6
  * LICENSE file in the root directory of this source tree.
7
7
  * ========================================================================== */
8
+ var __importDefault = (this && this.__importDefault) || function (mod) {
9
+ return (mod && mod.__esModule) ? mod : { "default": mod };
10
+ };
8
11
  Object.defineProperty(exports, "__esModule", { value: true });
9
12
  exports.createRequestSchema = exports.mergeAllOf = void 0;
13
+ const clsx_1 = __importDefault(require("clsx"));
10
14
  const createArrayBracket_1 = require("./createArrayBracket");
11
15
  const createDescription_1 = require("./createDescription");
12
16
  const createDetails_1 = require("./createDetails");
@@ -30,7 +34,7 @@ function mergeAllOf(allOf) {
30
34
  return true;
31
35
  },
32
36
  },
33
- ignoreAdditionalProperties: false,
37
+ ignoreAdditionalProperties: true,
34
38
  });
35
39
  const required = allOf.reduce((acc, cur) => {
36
40
  if (Array.isArray(cur.required)) {
@@ -47,7 +51,7 @@ exports.mergeAllOf = mergeAllOf;
47
51
  */
48
52
  function createAnyOneOf(schema) {
49
53
  const type = schema.oneOf ? "oneOf" : "anyOf";
50
- return (0, utils_1.create)("li", {
54
+ return (0, utils_1.create)("div", {
51
55
  children: [
52
56
  (0, utils_1.create)("span", {
53
57
  className: "badge badge--info",
@@ -61,12 +65,15 @@ function createAnyOneOf(schema) {
61
65
  const anyOneChildren = [];
62
66
  if (anyOneSchema.properties !== undefined) {
63
67
  anyOneChildren.push(createProperties(anyOneSchema));
68
+ delete anyOneSchema.properties;
64
69
  }
65
70
  if (anyOneSchema.allOf !== undefined) {
66
71
  anyOneChildren.push(createNodes(anyOneSchema));
72
+ delete anyOneSchema.allOf;
67
73
  }
68
74
  if (anyOneSchema.items !== undefined) {
69
75
  anyOneChildren.push(createItems(anyOneSchema));
76
+ delete anyOneSchema.items;
70
77
  }
71
78
  if (anyOneSchema.type === "string" ||
72
79
  anyOneSchema.type === "number" ||
@@ -144,6 +151,18 @@ function createAdditionalProperties(schema) {
144
151
  // }
145
152
  const additionalProperties = schema.additionalProperties;
146
153
  const type = additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.type;
154
+ // Handle free-form objects
155
+ if (String(additionalProperties) === "true" && schema.type === "object") {
156
+ return (0, utils_1.create)("SchemaItem", {
157
+ name: "property name*",
158
+ required: false,
159
+ schemaName: "any",
160
+ qualifierMessage: (0, schema_1.getQualifierMessage)(schema.additionalProperties),
161
+ schema: schema,
162
+ collapsible: false,
163
+ discriminator: false,
164
+ });
165
+ }
147
166
  if ((type === "object" || type === "array") &&
148
167
  ((additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.properties) ||
149
168
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.items) ||
@@ -152,9 +171,9 @@ function createAdditionalProperties(schema) {
152
171
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.oneOf) ||
153
172
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.anyOf))) {
154
173
  const title = additionalProperties.title;
155
- const schemaName = title ? `object (${title})` : "object";
174
+ const schemaName = (0, schema_1.getSchemaName)(additionalProperties);
156
175
  const required = (_a = schema.required) !== null && _a !== void 0 ? _a : false;
157
- return createDetailsNode("property name*", schemaName, additionalProperties, required, schema.nullable);
176
+ return createDetailsNode("property name*", title !== null && title !== void 0 ? title : schemaName, additionalProperties, required, schema.nullable);
158
177
  }
159
178
  if (((_b = schema.additionalProperties) === null || _b === void 0 ? void 0 : _b.type) === "string" ||
160
179
  ((_c = schema.additionalProperties) === null || _c === void 0 ? void 0 : _c.type) === "object" ||
@@ -164,41 +183,26 @@ function createAdditionalProperties(schema) {
164
183
  const additionalProperties = (_g = schema.additionalProperties) === null || _g === void 0 ? void 0 : _g.additionalProperties;
165
184
  if (additionalProperties !== undefined) {
166
185
  const type = (_j = (_h = schema.additionalProperties) === null || _h === void 0 ? void 0 : _h.additionalProperties) === null || _j === void 0 ? void 0 : _j.type;
167
- const format = (_l = (_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties) === null || _l === void 0 ? void 0 : _l.format;
168
- return (0, utils_1.create)("li", {
169
- children: (0, utils_1.create)("div", {
170
- children: [
171
- (0, utils_1.create)("code", { children: `property name*` }),
172
- (0, utils_1.guard)(type, (type) => (0, utils_1.create)("span", {
173
- style: { opacity: "0.6" },
174
- children: ` ${type}`,
175
- })),
176
- (0, utils_1.guard)(format, (format) => (0, utils_1.create)("span", {
177
- style: { opacity: "0.6" },
178
- children: ` (${format})`,
179
- })),
180
- (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema.additionalProperties), (message) => (0, utils_1.create)("div", {
181
- style: { marginTop: "var(--ifm-table-cell-padding)" },
182
- children: (0, createDescription_1.createDescription)(message),
183
- })),
184
- ],
185
- }),
186
+ const schemaName = (0, schema_1.getSchemaName)((_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties);
187
+ return (0, utils_1.create)("SchemaItem", {
188
+ name: "property name*",
189
+ required: false,
190
+ schemaName: schemaName !== null && schemaName !== void 0 ? schemaName : type,
191
+ qualifierMessage: (_l = schema.additionalProperties) !== null && _l !== void 0 ? _l : (0, schema_1.getQualifierMessage)(schema.additionalProperties),
192
+ schema: schema,
193
+ collapsible: false,
194
+ discriminator: false,
186
195
  });
187
196
  }
188
- return (0, utils_1.create)("li", {
189
- children: (0, utils_1.create)("div", {
190
- children: [
191
- (0, utils_1.create)("code", { children: `property name*` }),
192
- (0, utils_1.guard)(type, (type) => (0, utils_1.create)("span", {
193
- style: { opacity: "0.6" },
194
- children: ` ${type}`,
195
- })),
196
- (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema.additionalProperties), (message) => (0, utils_1.create)("div", {
197
- style: { marginTop: "var(--ifm-table-cell-padding)" },
198
- children: (0, createDescription_1.createDescription)(message),
199
- })),
200
- ],
201
- }),
197
+ const schemaName = (0, schema_1.getSchemaName)(schema.additionalProperties);
198
+ return (0, utils_1.create)("SchemaItem", {
199
+ name: "property name*",
200
+ required: false,
201
+ schemaName: schemaName,
202
+ qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
203
+ schema: schema.additionalProperties,
204
+ collapsible: false,
205
+ discriminator: false,
202
206
  });
203
207
  }
204
208
  return Object.entries(schema.additionalProperties).map(([key, val]) => createEdges({
@@ -396,32 +400,50 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
396
400
  children: [
397
401
  (0, createDetailsSummary_1.createDetailsSummary)({
398
402
  children: [
399
- (0, utils_1.create)("strong", { children: name }),
400
403
  (0, utils_1.create)("span", {
401
- style: { opacity: "0.6" },
402
- children: ` ${schemaName}`,
404
+ className: "openapi-schema__container",
405
+ children: [
406
+ (0, utils_1.create)("strong", {
407
+ className: (0, clsx_1.default)("openapi-schema__property", {
408
+ "openapi-schema__strikethrough": schema.deprecated,
409
+ }),
410
+ children: name,
411
+ }),
412
+ (0, utils_1.create)("span", {
413
+ className: "openapi-schema__name",
414
+ children: ` ${schemaName}`,
415
+ }),
416
+ (0, utils_1.guard)((Array.isArray(required)
417
+ ? required.includes(name)
418
+ : required === true) ||
419
+ schema.deprecated ||
420
+ nullable, () => [
421
+ (0, utils_1.create)("span", {
422
+ className: "openapi-schema__divider",
423
+ }),
424
+ ]),
425
+ (0, utils_1.guard)(nullable, () => [
426
+ (0, utils_1.create)("span", {
427
+ className: "openapi-schema__nullable",
428
+ children: "nullable",
429
+ }),
430
+ ]),
431
+ (0, utils_1.guard)(Array.isArray(required)
432
+ ? required.includes(name)
433
+ : required === true, () => [
434
+ (0, utils_1.create)("span", {
435
+ className: "openapi-schema__required",
436
+ children: "required",
437
+ }),
438
+ ]),
439
+ (0, utils_1.guard)(schema.deprecated, () => [
440
+ (0, utils_1.create)("span", {
441
+ className: "openapi-schema__deprecated",
442
+ children: "deprecated",
443
+ }),
444
+ ]),
445
+ ],
403
446
  }),
404
- (0, utils_1.guard)((schema.nullable && schema.nullable === true) ||
405
- (nullable && nullable === true), () => [
406
- (0, utils_1.create)("strong", {
407
- style: {
408
- fontSize: "var(--ifm-code-font-size)",
409
- color: "var(--openapi-nullable)",
410
- },
411
- children: " nullable",
412
- }),
413
- ]),
414
- (0, utils_1.guard)(Array.isArray(required)
415
- ? required.includes(name)
416
- : required === true, () => [
417
- (0, utils_1.create)("strong", {
418
- style: {
419
- fontSize: "var(--ifm-code-font-size)",
420
- color: "var(--openapi-required)",
421
- },
422
- children: " required",
423
- }),
424
- ]),
425
447
  ],
426
448
  }),
427
449
  (0, utils_1.create)("div", {
@@ -455,23 +477,28 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
455
477
  return undefined;
456
478
  }
457
479
  return (0, utils_1.create)("div", {
458
- className: "openapi-discriminator__item",
480
+ className: "openapi-discriminator__item openapi-schema__list-item",
459
481
  children: (0, utils_1.create)("div", {
460
482
  children: [
461
- (0, utils_1.create)("strong", { style: { paddingLeft: "1rem" }, children: name }),
462
- (0, utils_1.guard)(schemaName, (name) => (0, utils_1.create)("span", {
463
- style: { opacity: "0.6" },
464
- children: ` ${schemaName}`,
465
- })),
466
- (0, utils_1.guard)(required, () => [
467
- (0, utils_1.create)("strong", {
468
- style: {
469
- fontSize: "var(--ifm-code-font-size)",
470
- color: "var(--openapi-required)",
471
- },
472
- children: " required",
473
- }),
474
- ]),
483
+ (0, utils_1.create)("span", {
484
+ className: "openapi-schema__container",
485
+ children: [
486
+ (0, utils_1.create)("strong", {
487
+ className: "openapi-discriminator__name openapi-schema__property",
488
+ children: name,
489
+ }),
490
+ (0, utils_1.guard)(schemaName, (name) => (0, utils_1.create)("span", {
491
+ className: "openapi-schema__name",
492
+ children: ` ${schemaName}`,
493
+ })),
494
+ (0, utils_1.guard)(required, () => [
495
+ (0, utils_1.create)("span", {
496
+ className: "openapi-schema__required",
497
+ children: "required",
498
+ }),
499
+ ]),
500
+ ],
501
+ }),
475
502
  (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
476
503
  style: {
477
504
  paddingLeft: "1rem",
@@ -653,22 +680,22 @@ function createRequestSchema({ title, body, ...rest }) {
653
680
  value: `${mimeType}`,
654
681
  children: [
655
682
  (0, createDetails_1.createDetails)({
656
- className: "openapi-markdown__details",
683
+ className: "openapi-markdown__details mime",
657
684
  "data-collapsed": false,
658
685
  open: true,
659
686
  ...rest,
660
687
  children: [
661
688
  (0, createDetailsSummary_1.createDetailsSummary)({
662
- style: { textAlign: "left" },
689
+ className: "openapi-markdown__details-summary-mime",
663
690
  children: [
664
- (0, utils_1.create)("strong", { children: `${title}` }),
691
+ (0, utils_1.create)("h3", {
692
+ className: "openapi-markdown__details-summary-header-body",
693
+ children: `${title}`,
694
+ }),
665
695
  (0, utils_1.guard)(body.required && body.required === true, () => [
666
- (0, utils_1.create)("strong", {
667
- style: {
668
- fontSize: "var(--ifm-code-font-size)",
669
- color: "var(--openapi-required)",
670
- },
671
- children: " required",
696
+ (0, utils_1.create)("span", {
697
+ className: "openapi-schema__required",
698
+ children: "required",
672
699
  }),
673
700
  ]),
674
701
  ],
@@ -714,26 +741,26 @@ function createRequestSchema({ title, body, ...rest }) {
714
741
  value: `${randomFirstKey}-schema`,
715
742
  children: [
716
743
  (0, createDetails_1.createDetails)({
717
- className: "openapi-markdown__details",
744
+ className: "openapi-markdown__details mime",
718
745
  "data-collapsed": false,
719
746
  open: true,
720
747
  ...rest,
721
748
  children: [
722
749
  (0, createDetailsSummary_1.createDetailsSummary)({
723
- style: { textAlign: "left" },
750
+ className: "openapi-markdown__details-summary-mime",
724
751
  children: [
725
- (0, utils_1.create)("strong", { children: `${title}` }),
752
+ (0, utils_1.create)("h3", {
753
+ className: "openapi-markdown__details-summary-header-body",
754
+ children: `${title}`,
755
+ }),
726
756
  (0, utils_1.guard)(firstBody.type === "array", (format) => (0, utils_1.create)("span", {
727
757
  style: { opacity: "0.6" },
728
758
  children: ` array`,
729
759
  })),
730
760
  (0, utils_1.guard)(body.required, () => [
731
761
  (0, utils_1.create)("strong", {
732
- style: {
733
- fontSize: "var(--ifm-code-font-size)",
734
- color: "var(--openapi-required)",
735
- },
736
- children: " required",
762
+ className: "openapi-schema__required",
763
+ children: "required",
737
764
  }),
738
765
  ]),
739
766
  ],