docusaurus-plugin-openapi-docs 0.0.0-827 → 0.0.0-832

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 (8) hide show
  1. package/README.md +17 -7
  2. package/lib/options.js +4 -0
  3. package/lib/sidebars/index.js +32 -26
  4. package/lib/types.d.ts +9 -0
  5. package/package.json +2 -2
  6. package/src/options.ts +5 -0
  7. package/src/sidebars/index.ts +47 -40
  8. package/src/types.ts +11 -0
package/README.md CHANGED
@@ -174,13 +174,15 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
174
174
 
175
175
  `sidebarOptions` can be configured with the following options:
176
176
 
177
- | Name | Type | Default | Description |
178
- | -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
179
- | `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. |
180
- | `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. |
181
- | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
182
- | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
183
- | `customProps` | `object` | `null` | Additional props for customizing a sidebar item. |
177
+ | Name | Type | Default | Description |
178
+ | -------------------- | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
179
+ | `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. |
180
+ | `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. |
181
+ | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
182
+ | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
183
+ | `customProps` | `object` | `null` | Additional props for customizing a sidebar item. |
184
+ | `sidebarGenerators` | `object` | `null` | Optional: Customize sidebar rendering with callback functions. |
185
+ | `createDocItem` | `function` | `null` | Optional: Returns a `SidebarItemDoc` object, which allows for customisation of sidebar items. For example, add a class name in certain conditions, or add `customProps` to provide custom rendering. See below for a list of supported operations. |
184
186
 
185
187
  > 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`.
186
188
 
@@ -206,6 +208,14 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
206
208
  | `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
207
209
  | `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
208
210
 
211
+ ### sidebarGenerators
212
+
213
+ `sidebarGenerators` can be configured with the following options:
214
+
215
+ | Name | Type | Default | Description |
216
+ | --------------- | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
217
+ | `createDocItem` | `function` | `null` | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type** `(item: ApiPageMetadata | SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
218
+
209
219
  ## CLI Usage
210
220
 
211
221
  ```bash
package/lib/options.js CHANGED
@@ -8,12 +8,16 @@
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
9
  exports.OptionsSchema = void 0;
10
10
  const utils_validation_1 = require("@docusaurus/utils-validation");
11
+ const sidebarGenerators = utils_validation_1.Joi.object({
12
+ createDocItem: utils_validation_1.Joi.function(),
13
+ });
11
14
  const sidebarOptions = utils_validation_1.Joi.object({
12
15
  groupPathsBy: utils_validation_1.Joi.string().valid("tag", "tagGroup"),
13
16
  categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info", "auto"),
14
17
  customProps: utils_validation_1.Joi.object(),
15
18
  sidebarCollapsible: utils_validation_1.Joi.boolean(),
16
19
  sidebarCollapsed: utils_validation_1.Joi.boolean(),
20
+ sidebarGenerators: sidebarGenerators,
17
21
  });
18
22
  const markdownGenerators = utils_validation_1.Joi.object({
19
23
  createApiPageMD: utils_validation_1.Joi.function(),
package/lib/sidebars/index.js CHANGED
@@ -23,11 +23,33 @@ function isInfoItem(item) {
23
23
  function isSchemaItem(item) {
24
24
  return item.type === "schema";
25
25
  }
26
+ const createDocItem = (item, { sidebarOptions: { customProps }, basePath }) => {
27
+ var _a, _b;
28
+ const sidebar_label = item.frontMatter.sidebar_label;
29
+ const title = item.title;
30
+ const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
31
+ const className = item.type === "api"
32
+ ? (0, clsx_1.default)({
33
+ "menu__list-item--deprecated": item.api.deprecated,
34
+ "api-method": !!item.api.method,
35
+ }, item.api.method)
36
+ : (0, clsx_1.default)({
37
+ "menu__list-item--deprecated": item.schema.deprecated,
38
+ }, "schema");
39
+ return {
40
+ type: "doc",
41
+ id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
42
+ label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
43
+ customProps: customProps,
44
+ className: className ? className : undefined,
45
+ };
46
+ };
26
47
  function groupByTags(items, sidebarOptions, options, tags, docPath) {
48
+ var _a, _b;
27
49
  let { outputDir, label, showSchemas } = options;
28
50
  // Remove trailing slash before proceeding
29
51
  outputDir = outputDir.replace(/\/$/, "");
30
- const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
52
+ const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } = sidebarOptions;
31
53
  const apiItems = items.filter(isApiItem);
32
54
  const infoItems = items.filter(isInfoItem);
33
55
  const schemaItems = items.filter(isSchemaItem);
@@ -61,27 +83,11 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
61
83
  const basePath = docPath
62
84
  ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
63
85
  : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
64
- function createDocItem(item) {
65
- var _a, _b;
66
- const sidebar_label = item.frontMatter.sidebar_label;
67
- const title = item.title;
68
- const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
69
- const className = item.type === "api"
70
- ? (0, clsx_1.default)({
71
- "menu__list-item--deprecated": item.api.deprecated,
72
- "api-method": !!item.api.method,
73
- }, item.api.method)
74
- : (0, clsx_1.default)({
75
- "menu__list-item--deprecated": item.schema.deprecated,
76
- }, "schema");
77
- return {
78
- type: "doc",
79
- id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
80
- label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
81
- customProps: customProps,
82
- className: className ? className : undefined,
83
- };
84
- }
86
+ const createDocItemFnContext = {
87
+ sidebarOptions,
88
+ basePath,
89
+ };
90
+ const createDocItemFn = (_b = (_a = sidebarOptions.sidebarGenerators) === null || _a === void 0 ? void 0 : _a.createDocItem) !== null && _b !== void 0 ? _b : createDocItem;
85
91
  let rootIntroDoc = undefined;
86
92
  if (infoItems.length === 1) {
87
93
  const infoItem = infoItems[0];
@@ -139,14 +145,14 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
139
145
  link: linkConfig,
140
146
  collapsible: sidebarCollapsible,
141
147
  collapsed: sidebarCollapsed,
142
- items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
148
+ items: [...taggedSchemaItems, ...taggedApiItems].map((item) => createDocItemFn(item, createDocItemFnContext)),
143
149
  };
144
150
  })
145
151
  .filter((item) => item.items.length > 0); // Filter out any categories with no items.
146
152
  // Handle items with no tag
147
153
  const untaggedItems = apiItems
148
154
  .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
149
- .map(createDocItem);
155
+ .map((item) => createDocItemFn(item, createDocItemFnContext));
150
156
  let untagged = [];
151
157
  if (untaggedItems.length > 0) {
152
158
  untagged = [
@@ -157,7 +163,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
157
163
  collapsed: sidebarCollapsed,
158
164
  items: apiItems
159
165
  .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
160
- .map(createDocItem),
166
+ .map((item) => createDocItemFn(item, createDocItemFnContext)),
161
167
  },
162
168
  ];
163
169
  }
@@ -171,7 +177,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
171
177
  collapsed: sidebarCollapsed,
172
178
  items: schemaItems
173
179
  .filter(({ schema }) => !schema["x-tags"])
174
- .map(createDocItem),
180
+ .map((item) => createDocItemFn(item, createDocItemFnContext)),
175
181
  },
176
182
  ];
177
183
  }
package/lib/types.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
1
2
  import type Request from "postman-collection";
2
3
  import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
3
4
  export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
@@ -34,6 +35,13 @@ export interface MarkdownGenerator {
34
35
  createTagPageMD?: (pageData: TagPageMetadata) => string;
35
36
  createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
36
37
  }
38
+ export type ApiDocItemGenerator = (item: ApiPageMetadata | SchemaPageMetadata, context: {
39
+ sidebarOptions: SidebarOptions;
40
+ basePath: string;
41
+ }) => SidebarItemDoc;
42
+ export interface SidebarGenerators {
43
+ createDocItem?: ApiDocItemGenerator;
44
+ }
37
45
  export interface SidebarOptions {
38
46
  groupPathsBy?: string;
39
47
  categoryLinkSource?: "info" | "tag" | "auto";
@@ -42,6 +50,7 @@ export interface SidebarOptions {
42
50
  };
43
51
  sidebarCollapsible?: boolean;
44
52
  sidebarCollapsed?: boolean;
53
+ sidebarGenerators?: SidebarGenerators;
45
54
  }
46
55
  export interface APIVersionOptions {
47
56
  specPath: string;
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-827",
4
+ "version": "0.0.0-832",
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": "759e2c14c7471bcc90a83071407fb0a8fd47ec35"
65
+ "gitHead": "ea399ebfb6b1c0ec7e50ed4bfb299d634705b06a"
66
66
  }
package/src/options.ts CHANGED
@@ -7,12 +7,17 @@
7
7
 
8
8
  import { Joi } from "@docusaurus/utils-validation";
9
9
 
10
+ const sidebarGenerators = Joi.object({
11
+ createDocItem: Joi.function(),
12
+ });
13
+
10
14
  const sidebarOptions = Joi.object({
11
15
  groupPathsBy: Joi.string().valid("tag", "tagGroup"),
12
16
  categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
13
17
  customProps: Joi.object(),
14
18
  sidebarCollapsible: Joi.boolean(),
15
19
  sidebarCollapsed: Joi.boolean(),
20
+ sidebarGenerators: sidebarGenerators,
16
21
  });
17
22
 
18
23
  const markdownGenerators = Joi.object({
package/src/sidebars/index.ts CHANGED
@@ -12,7 +12,6 @@ import {
12
12
  ProcessedSidebar,
13
13
  SidebarItemCategory,
14
14
  SidebarItemCategoryLinkConfig,
15
- SidebarItemDoc,
16
15
  } from "@docusaurus/plugin-content-docs/src/sidebars/types";
17
16
  import { posixPath } from "@docusaurus/utils";
18
17
  import clsx from "clsx";
@@ -27,6 +26,7 @@ import type {
27
26
  ApiMetadata,
28
27
  InfoPageMetadata,
29
28
  SchemaPageMetadata,
29
+ ApiDocItemGenerator,
30
30
  } from "../types";
31
31
 
32
32
  function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -41,6 +41,37 @@ function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
41
41
  return item.type === "schema";
42
42
  }
43
43
 
44
+ const createDocItem: ApiDocItemGenerator = (
45
+ item,
46
+ { sidebarOptions: { customProps }, basePath }
47
+ ) => {
48
+ const sidebar_label = item.frontMatter.sidebar_label;
49
+ const title = item.title;
50
+ const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
51
+ const className =
52
+ item.type === "api"
53
+ ? clsx(
54
+ {
55
+ "menu__list-item--deprecated": item.api.deprecated,
56
+ "api-method": !!item.api.method,
57
+ },
58
+ item.api.method
59
+ )
60
+ : clsx(
61
+ {
62
+ "menu__list-item--deprecated": item.schema.deprecated,
63
+ },
64
+ "schema"
65
+ );
66
+ return {
67
+ type: "doc" as const,
68
+ id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
69
+ label: (sidebar_label as string) ?? title ?? id,
70
+ customProps: customProps,
71
+ className: className ? className : undefined,
72
+ };
73
+ };
74
+
44
75
  function groupByTags(
45
76
  items: ApiMetadata[],
46
77
  sidebarOptions: SidebarOptions,
@@ -53,12 +84,8 @@ function groupByTags(
53
84
  // Remove trailing slash before proceeding
54
85
  outputDir = outputDir.replace(/\/$/, "");
55
86
 
56
- const {
57
- sidebarCollapsed,
58
- sidebarCollapsible,
59
- customProps,
60
- categoryLinkSource,
61
- } = sidebarOptions;
87
+ const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } =
88
+ sidebarOptions;
62
89
 
63
90
  const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
64
91
  const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
@@ -101,35 +128,13 @@ function groupByTags(
101
128
  const basePath = docPath
102
129
  ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
103
130
  : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
104
- function createDocItem(
105
- item: ApiPageMetadata | SchemaPageMetadata
106
- ): SidebarItemDoc {
107
- const sidebar_label = item.frontMatter.sidebar_label;
108
- const title = item.title;
109
- const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
110
- const className =
111
- item.type === "api"
112
- ? clsx(
113
- {
114
- "menu__list-item--deprecated": item.api.deprecated,
115
- "api-method": !!item.api.method,
116
- },
117
- item.api.method
118
- )
119
- : clsx(
120
- {
121
- "menu__list-item--deprecated": item.schema.deprecated,
122
- },
123
- "schema"
124
- );
125
- return {
126
- type: "doc" as const,
127
- id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
128
- label: (sidebar_label as string) ?? title ?? id,
129
- customProps: customProps,
130
- className: className ? className : undefined,
131
- };
132
- }
131
+
132
+ const createDocItemFnContext = {
133
+ sidebarOptions,
134
+ basePath,
135
+ };
136
+ const createDocItemFn =
137
+ sidebarOptions.sidebarGenerators?.createDocItem ?? createDocItem;
133
138
 
134
139
  let rootIntroDoc = undefined;
135
140
  if (infoItems.length === 1) {
@@ -208,7 +213,9 @@ function groupByTags(
208
213
  link: linkConfig,
209
214
  collapsible: sidebarCollapsible,
210
215
  collapsed: sidebarCollapsed,
211
- items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
216
+ items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
217
+ createDocItemFn(item, createDocItemFnContext)
218
+ ),
212
219
  };
213
220
  })
214
221
  .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -216,7 +223,7 @@ function groupByTags(
216
223
  // Handle items with no tag
217
224
  const untaggedItems = apiItems
218
225
  .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
219
- .map(createDocItem);
226
+ .map((item) => createDocItemFn(item, createDocItemFnContext));
220
227
  let untagged: SidebarItemCategory[] = [];
221
228
  if (untaggedItems.length > 0) {
222
229
  untagged = [
@@ -227,7 +234,7 @@ function groupByTags(
227
234
  collapsed: sidebarCollapsed!,
228
235
  items: apiItems
229
236
  .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
230
- .map(createDocItem),
237
+ .map((item) => createDocItemFn(item, createDocItemFnContext)),
231
238
  },
232
239
  ];
233
240
  }
@@ -242,7 +249,7 @@ function groupByTags(
242
249
  collapsed: sidebarCollapsed!,
243
250
  items: schemaItems
244
251
  .filter(({ schema }) => !schema["x-tags"])
245
- .map(createDocItem),
252
+ .map((item) => createDocItemFn(item, createDocItemFnContext)),
246
253
  },
247
254
  ];
248
255
  }
package/src/types.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  * ========================================================================== */
7
7
 
8
+ import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
8
9
  import type Request from "postman-collection";
9
10
 
10
11
  import {
@@ -57,12 +58,22 @@ export interface MarkdownGenerator {
57
58
  createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
58
59
  }
59
60
 
61
+ export type ApiDocItemGenerator = (
62
+ item: ApiPageMetadata | SchemaPageMetadata,
63
+ context: { sidebarOptions: SidebarOptions; basePath: string }
64
+ ) => SidebarItemDoc;
65
+
66
+ export interface SidebarGenerators {
67
+ createDocItem?: ApiDocItemGenerator;
68
+ }
69
+
60
70
  export interface SidebarOptions {
61
71
  groupPathsBy?: string;
62
72
  categoryLinkSource?: "info" | "tag" | "auto";
63
73
  customProps?: { [key: string]: unknown };
64
74
  sidebarCollapsible?: boolean;
65
75
  sidebarCollapsed?: boolean;
76
+ sidebarGenerators?: SidebarGenerators;
66
77
  }
67
78
 
68
79
  export interface APIVersionOptions {