docusaurus-plugin-openapi-docs 1.7.1 → 1.7.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.
Files changed (13) hide show
  1. package/lib/index.js +8 -4
  2. package/lib/markdown/createRequestSchema.js +167 -101
  3. package/lib/markdown/createResponseSchema.js +167 -101
  4. package/lib/openapi/utils/loadAndResolveSpec.js +9 -2
  5. package/lib/options.js +6 -0
  6. package/lib/types.d.ts +6 -0
  7. package/package.json +4 -4
  8. package/src/index.ts +18 -5
  9. package/src/markdown/createRequestSchema.ts +192 -125
  10. package/src/markdown/createResponseSchema.ts +192 -125
  11. package/src/openapi/utils/loadAndResolveSpec.ts +10 -1
  12. package/src/options.ts +7 -0
  13. package/src/types.ts +7 -0
package/lib/index.js CHANGED
@@ -76,7 +76,8 @@ function pluginOpenAPIDocs(context, options) {
76
76
  let docRouteBasePath = docData ? docData.routeBasePath : undefined;
77
77
  let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
78
78
  async function generateApiDocs(options, pluginId) {
79
- let { specPath, outputDir, template, downloadUrl, sidebarOptions } = options;
79
+ var _a, _b, _c;
80
+ let { specPath, outputDir, template, markdownGenerators, downloadUrl, sidebarOptions, } = options;
80
81
  // Remove trailing slash before proceeding
81
82
  outputDir = outputDir.replace(/\/$/, "");
82
83
  // Override docPath if pluginId provided
@@ -193,6 +194,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
193
194
  <DocCardList items={useCurrentSidebarCategory().items}/>
194
195
  \`\`\`
195
196
  `;
197
+ const apiPageGenerator = (_a = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createApiPageMD) !== null && _a !== void 0 ? _a : markdown_1.createApiPageMD;
198
+ const infoPageGenerator = (_b = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createInfoPageMD) !== null && _b !== void 0 ? _b : markdown_1.createInfoPageMD;
199
+ const tagPageGenerator = (_c = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createTagPageMD) !== null && _c !== void 0 ? _c : markdown_1.createTagPageMD;
196
200
  loadedApi.map(async (item) => {
197
201
  if (item.type === "info") {
198
202
  if (downloadUrl && isURL(downloadUrl)) {
@@ -200,10 +204,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
200
204
  }
201
205
  }
202
206
  const markdown = item.type === "api"
203
- ? (0, markdown_1.createApiPageMD)(item)
207
+ ? apiPageGenerator(item)
204
208
  : item.type === "info"
205
- ? (0, markdown_1.createInfoPageMD)(item)
206
- : (0, markdown_1.createTagPageMD)(item);
209
+ ? infoPageGenerator(item)
210
+ : tagPageGenerator(item);
207
211
  item.markdown = markdown;
208
212
  if (item.type === "api") {
209
213
  item.json = JSON.stringify(item.api);
package/lib/markdown/createRequestSchema.js CHANGED
@@ -47,7 +47,7 @@ exports.mergeAllOf = mergeAllOf;
47
47
  */
48
48
  function createAnyOneOf(schema) {
49
49
  const type = schema.oneOf ? "oneOf" : "anyOf";
50
- return (0, utils_1.create)("li", {
50
+ return (0, utils_1.create)("div", {
51
51
  children: [
52
52
  (0, utils_1.create)("span", {
53
53
  className: "badge badge--info",
@@ -61,12 +61,15 @@ function createAnyOneOf(schema) {
61
61
  const anyOneChildren = [];
62
62
  if (anyOneSchema.properties !== undefined) {
63
63
  anyOneChildren.push(createProperties(anyOneSchema));
64
+ delete anyOneSchema.properties;
64
65
  }
65
66
  if (anyOneSchema.allOf !== undefined) {
66
67
  anyOneChildren.push(createNodes(anyOneSchema));
68
+ delete anyOneSchema.allOf;
67
69
  }
68
70
  if (anyOneSchema.items !== undefined) {
69
71
  anyOneChildren.push(createItems(anyOneSchema));
72
+ delete anyOneSchema.items;
70
73
  }
71
74
  if (anyOneSchema.type === "string" ||
72
75
  anyOneSchema.type === "number" ||
@@ -144,6 +147,18 @@ function createAdditionalProperties(schema) {
144
147
  // }
145
148
  const additionalProperties = schema.additionalProperties;
146
149
  const type = additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.type;
150
+ // Handle free-form objects
151
+ if (String(additionalProperties) === "true" && schema.type === "object") {
152
+ return (0, utils_1.create)("SchemaItem", {
153
+ name: "property name*",
154
+ required: false,
155
+ schemaName: "any",
156
+ qualifierMessage: (0, schema_1.getQualifierMessage)(schema.additionalProperties),
157
+ schema: schema,
158
+ collapsible: false,
159
+ discriminator: false,
160
+ });
161
+ }
147
162
  if ((type === "object" || type === "array") &&
148
163
  ((additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.properties) ||
149
164
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.items) ||
@@ -152,9 +167,9 @@ function createAdditionalProperties(schema) {
152
167
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.oneOf) ||
153
168
  (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.anyOf))) {
154
169
  const title = additionalProperties.title;
155
- const schemaName = title ? `object (${title})` : "object";
170
+ const schemaName = (0, schema_1.getSchemaName)(additionalProperties);
156
171
  const required = (_a = schema.required) !== null && _a !== void 0 ? _a : false;
157
- return createDetailsNode("property name*", schemaName, additionalProperties, required, schema.nullable);
172
+ return createDetailsNode("property name*", title !== null && title !== void 0 ? title : schemaName, additionalProperties, required, schema.nullable);
158
173
  }
159
174
  if (((_b = schema.additionalProperties) === null || _b === void 0 ? void 0 : _b.type) === "string" ||
160
175
  ((_c = schema.additionalProperties) === null || _c === void 0 ? void 0 : _c.type) === "object" ||
@@ -164,41 +179,26 @@ function createAdditionalProperties(schema) {
164
179
  const additionalProperties = (_g = schema.additionalProperties) === null || _g === void 0 ? void 0 : _g.additionalProperties;
165
180
  if (additionalProperties !== undefined) {
166
181
  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
- }),
182
+ const schemaName = (0, schema_1.getSchemaName)((_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties);
183
+ return (0, utils_1.create)("SchemaItem", {
184
+ name: "property name*",
185
+ required: false,
186
+ schemaName: schemaName !== null && schemaName !== void 0 ? schemaName : type,
187
+ qualifierMessage: (_l = schema.additionalProperties) !== null && _l !== void 0 ? _l : (0, schema_1.getQualifierMessage)(schema.additionalProperties),
188
+ schema: schema,
189
+ collapsible: false,
190
+ discriminator: false,
186
191
  });
187
192
  }
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
- }),
193
+ const schemaName = (0, schema_1.getSchemaName)(schema.additionalProperties);
194
+ return (0, utils_1.create)("SchemaItem", {
195
+ name: "property name*",
196
+ required: false,
197
+ schemaName: schemaName,
198
+ qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
199
+ schema: schema.additionalProperties,
200
+ collapsible: false,
201
+ discriminator: false,
202
202
  });
203
203
  }
204
204
  return Object.entries(schema.additionalProperties).map(([key, val]) => createEdges({
@@ -442,6 +442,86 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
442
442
  ],
443
443
  });
444
444
  }
445
+ function createOneOfProperty(name, schemaName, schema, required, nullable) {
446
+ return (0, utils_1.create)("SchemaItem", {
447
+ collapsible: true,
448
+ className: "schemaItem",
449
+ children: [
450
+ (0, createDetails_1.createDetails)({
451
+ children: [
452
+ (0, createDetailsSummary_1.createDetailsSummary)({
453
+ children: [
454
+ (0, utils_1.create)("strong", { children: name }),
455
+ (0, utils_1.create)("span", {
456
+ style: { opacity: "0.6" },
457
+ children: ` ${schemaName}`,
458
+ }),
459
+ (0, utils_1.guard)((schema.nullable && schema.nullable === true) ||
460
+ (nullable && nullable === true), () => [
461
+ (0, utils_1.create)("strong", {
462
+ style: {
463
+ fontSize: "var(--ifm-code-font-size)",
464
+ color: "var(--openapi-nullable)",
465
+ },
466
+ children: " nullable",
467
+ }),
468
+ ]),
469
+ (0, utils_1.guard)(Array.isArray(required)
470
+ ? required.includes(name)
471
+ : required === true, () => [
472
+ (0, utils_1.create)("strong", {
473
+ style: {
474
+ fontSize: "var(--ifm-code-font-size)",
475
+ color: "var(--openapi-required)",
476
+ },
477
+ children: " required",
478
+ }),
479
+ ]),
480
+ ],
481
+ }),
482
+ (0, utils_1.create)("div", {
483
+ style: { marginLeft: "1rem" },
484
+ children: [
485
+ (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
486
+ style: { marginTop: ".5rem", marginBottom: ".5rem" },
487
+ children: (0, createDescription_1.createDescription)(message),
488
+ })),
489
+ (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
490
+ style: { marginTop: ".5rem", marginBottom: ".5rem" },
491
+ children: (0, createDescription_1.createDescription)(description),
492
+ })),
493
+ ],
494
+ }),
495
+ (0, utils_1.create)("div", {
496
+ children: [
497
+ (0, utils_1.create)("span", {
498
+ className: "badge badge--info",
499
+ children: "oneOf",
500
+ }),
501
+ (0, utils_1.create)("SchemaTabs", {
502
+ children: schema["oneOf"].map((property, index) => {
503
+ var _a;
504
+ const label = (_a = property.type) !== null && _a !== void 0 ? _a : `MOD${index + 1}`;
505
+ return (0, utils_1.create)("TabItem", {
506
+ label: label,
507
+ value: `${index}-property`,
508
+ children: [
509
+ (0, utils_1.create)("p", { children: label }),
510
+ (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
511
+ style: { marginTop: ".5rem", marginBottom: ".5rem" },
512
+ children: (0, createDescription_1.createDescription)(description),
513
+ })),
514
+ ],
515
+ });
516
+ }),
517
+ }),
518
+ ],
519
+ }),
520
+ ],
521
+ }),
522
+ ],
523
+ });
524
+ }
445
525
  /**
446
526
  * For handling discriminators that map to a same-level property (like 'petType').
447
527
  * Note: These should only be encountered while iterating through properties.
@@ -453,53 +533,26 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
453
533
  if (discriminator.mapping === undefined) {
454
534
  return undefined;
455
535
  }
456
- return (0, utils_1.create)("div", {
457
- className: "discriminatorItem",
458
- children: (0, utils_1.create)("div", {
459
- children: [
460
- (0, utils_1.create)("strong", { style: { paddingLeft: "1rem" }, children: name }),
461
- (0, utils_1.guard)(schemaName, (name) => (0, utils_1.create)("span", {
462
- style: { opacity: "0.6" },
463
- children: ` ${schemaName}`,
464
- })),
465
- (0, utils_1.guard)(required, () => [
466
- (0, utils_1.create)("strong", {
467
- style: {
468
- fontSize: "var(--ifm-code-font-size)",
469
- color: "var(--openapi-required)",
470
- },
471
- children: " required",
472
- }),
473
- ]),
474
- (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
475
- style: {
476
- paddingLeft: "1rem",
477
- },
478
- children: (0, createDescription_1.createDescription)(message),
479
- })),
480
- (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
481
- style: {
482
- paddingLeft: "1rem",
483
- },
484
- children: (0, createDescription_1.createDescription)(description),
485
- })),
486
- (0, utils_1.create)("DiscriminatorTabs", {
487
- children: Object.keys(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping).map((key, index) => {
488
- const label = key;
489
- return (0, utils_1.create)("TabItem", {
490
- label: label,
491
- value: `${index}-item-discriminator`,
492
- children: [
493
- (0, utils_1.create)("div", {
494
- style: { marginLeft: "-4px" },
495
- children: createNodes(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping[key]),
496
- }),
497
- ],
498
- });
499
- }),
536
+ return (0, utils_1.create)("SchemaItem", {
537
+ name,
538
+ required: Array.isArray(required) ? required.includes(name) : required,
539
+ schemaName: schemaName,
540
+ qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
541
+ schema: schema,
542
+ collapsible: false,
543
+ discriminator: true,
544
+ children: [
545
+ (0, utils_1.create)("DiscriminatorTabs", {
546
+ children: Object.keys(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping).map((key, index) => {
547
+ const label = key;
548
+ return (0, utils_1.create)("TabItem", {
549
+ label: label,
550
+ value: `${index}-item-discriminator`,
551
+ children: createNodes(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping[key]),
552
+ });
500
553
  }),
501
- ],
502
- }),
554
+ }),
555
+ ],
503
556
  });
504
557
  }
505
558
  /**
@@ -512,7 +565,7 @@ function createEdges({ name, schema, required, discriminator, }) {
512
565
  return createPropertyDiscriminator(name, "string", schema, discriminator, required);
513
566
  }
514
567
  if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
515
- return createDetailsNode(name, schemaName, schema, required, schema.nullable);
568
+ return createOneOfProperty(name, schemaName, schema, required, schema.nullable);
516
569
  }
517
570
  if (schema.allOf !== undefined) {
518
571
  const { mergedSchemas, required, } = mergeAllOf(schema.allOf);
@@ -602,24 +655,37 @@ function createNodes(schema) {
602
655
  }
603
656
  // primitive
604
657
  if (schema.type !== undefined) {
605
- return (0, utils_1.create)("li", {
606
- children: (0, utils_1.create)("div", {
607
- children: [
608
- (0, utils_1.create)("strong", { children: schema.type }),
609
- (0, utils_1.guard)(schema.format, (format) => (0, utils_1.create)("span", {
610
- style: { opacity: "0.6" },
611
- children: ` ${format}`,
612
- })),
613
- (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
614
- style: { marginTop: "var(--ifm-table-cell-padding)" },
615
- children: (0, createDescription_1.createDescription)(message),
616
- })),
617
- (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
618
- style: { marginTop: "var(--ifm-table-cell-padding)" },
619
- children: (0, createDescription_1.createDescription)(description),
620
- })),
621
- ],
622
- }),
658
+ if (schema.allOf) {
659
+ //handle circular result in allOf
660
+ if (schema.allOf.length && typeof schema.allOf[0] === "string") {
661
+ return (0, utils_1.create)("div", {
662
+ style: {
663
+ marginTop: ".5rem",
664
+ marginBottom: ".5rem",
665
+ marginLeft: "1rem",
666
+ },
667
+ children: (0, createDescription_1.createDescription)(schema.allOf[0]),
668
+ });
669
+ }
670
+ }
671
+ return (0, utils_1.create)("div", {
672
+ style: {
673
+ marginTop: ".5rem",
674
+ marginBottom: ".5rem",
675
+ marginLeft: "1rem",
676
+ },
677
+ children: (0, createDescription_1.createDescription)(schema.type),
678
+ });
679
+ }
680
+ // handle circular references
681
+ if (typeof schema === "string") {
682
+ return (0, utils_1.create)("div", {
683
+ style: {
684
+ marginTop: ".5rem",
685
+ marginBottom: ".5rem",
686
+ marginLeft: "1rem",
687
+ },
688
+ children: [(0, createDescription_1.createDescription)(schema)],
623
689
  });
624
690
  }
625
691
  // Unknown node/schema type should return undefined