Skip to content

Commit e146cc5

Browse files
sserratabencagriImFlogchranmatzitcam
authored
V2 feature parity (#742)
* feat: implement x-tagGroup feature (#737) * impement redoc's x-tagGroup feature * merge main * update documentation * fix filtered tags by group * remove tracked .idea files * add option to readme * merge main * fix lint * revert yarn.lock and linter * cleanup missing types, dup imports and add restaurant example * fix: Guard only undefined and empty strings (#725) * Conditional display of header Request (#719) Co-authored-by: Christian A. Mathiesen <christian@zaveit.no> * update lock file * feat: Implement schema pages behind a config option `showSchemas` (#736) * feat: Implement schema pages behind a config option `showSchemas` * Add `showSchemas` to petstore demo * address linter errors * enable schemas for petstore * update lock file * add missing heading import * address linter errors --------- Co-authored-by: Çağrı S <bencagri@users.noreply.github.com> Co-authored-by: Florian Garcia <garcia.florian.perso@gmail.com> Co-authored-by: chranmat <cam@mathix.net> Co-authored-by: Christian A. Mathiesen <christian@zaveit.no> Co-authored-by: Marc L <littlemarc2020@gmail.com>
1 parent 47d7bdd commit e146cc5

File tree

23 files changed

+540
-63
lines changed

23 files changed

+540
-63
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,8 @@ dist
137137
demo/**/*.api.mdx
138138
demo/**/*.info.mdx
139139
demo/**/*.tag.mdx
140+
demo/**/*.schema.mdx
140141
demo/**/sidebar.ts
141142
demo/**/versions.json
142143

144+
.idea

‎README.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -169,12 +169,13 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
169169
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
170170
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
171171
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
172+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |
172173

173174
`sidebarOptions` can be configured with the following options:
174175

175176
| Name | Type | Default | Description |
176177
| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
177-
| `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`. |
178179
| `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. |
179180
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
180181
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
@@ -197,11 +198,12 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
197198

198199
`markdownGenerators` can be configured with the following options:
199200

200-
| Name | Type | Default | Description |
201-
| ------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
202-
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
203-
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
204-
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
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` |
205207

206208
## CLI Usage
207209

‎demo/docs/intro.mdx

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
336336
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
337337
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
338338
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
339+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |
339340

340341
### sidebarOptions
341342

@@ -373,11 +374,12 @@ All versions will automatically inherit `sidebarOptions` from the parent/base co
373374

374375
`markdownGenerators` can be configured with the following options:
375376

376-
| Name | Type | Default | Description |
377-
| ------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------|
378-
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
379-
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
380-
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
377+
| Name | Type | Default | Description |
378+
| ------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------|
379+
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
380+
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
381+
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
382+
| `createSchemaPageMD`| `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
381383

382384
:::info NOTE
383385
If a config option is not provided, its default markdown generator will be used.

‎demo/docs/sidebars.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ For greater control, you also have the option of constructing the sidebar object
5151

5252
The OpenAPI docs plugin provides out-of-the-box support for grouping paths by "tag". What this means is that the plugin will automatically generate a sidebar slice using the first path tag as the "group by" value and the path itself as one of the `items` under that category.
5353

54+
### Grouping by TagGroup
55+
56+
The OpenAPI docs plugin provides out-of-the-box support for grouping paths by "tagGroup".
57+
What this means is that the plugin will automatically generate a sidebar slice using the first path group as the "group by" value and the path itself as one of the `tags` under that category.
58+
Use `x-tagGroups` to group tags in the [Reference](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) docs navigation sidebar. Add it to the root OpenAPI object.
59+
5460
### Category Links
5561

5662
Docusaurus now supports the ability to designate or customize what page gets displayed when a category is clicked.

‎demo/docusaurus.config.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,7 @@ const config: Config = {
243243
downloadUrl:
244244
"https://raw.githubusercontent.com/PaloAltoNetworks/docusaurus-openapi-docs/main/demo/examples/petstore.yaml",
245245
hideSendButton: false,
246+
showSchemas: true,
246247
} satisfies OpenApiPlugin.Options,
247248
cos: {
248249
specPath: "examples/openapi-cos.json",
@@ -259,6 +260,13 @@ const config: Config = {
259260
specPath: "examples/food/yogurtstore/openapi.yaml",
260261
outputDir: "docs/food/yogurtstore",
261262
} satisfies OpenApiPlugin.Options,
263+
restaurant: {
264+
specPath: "examples/food/restaurant/openapi.yaml",
265+
outputDir: "docs/restaurant",
266+
sidebarOptions: {
267+
groupPathsBy: "tagGroup",
268+
},
269+
} satisfies OpenApiPlugin.Options,
262270
} satisfies Plugin.PluginOptions,
263271
},
264272
],

‎demo/examples/food/restaurant/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Restaurant",
3+
"collapsed": true
4+
}

‎demo/examples/food/restaurant/openapi.yaml

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Restaurant Example
4+
version: 1.0.0
5+
description: Sample description.
6+
paths:
7+
/menu:
8+
get:
9+
tags:
10+
- tag1
11+
summary: Get Menu
12+
description: Froyo's the best!
13+
responses:
14+
200:
15+
description: OK
16+
/products:
17+
get:
18+
tags:
19+
- tag1
20+
- tag2
21+
summary: List All Products
22+
description: Froyo's the best!
23+
responses:
24+
200:
25+
description: OK
26+
/drinks:
27+
get:
28+
tags:
29+
- tag1
30+
- tag2
31+
summary: List All Drinks
32+
description: Froyo's the best!
33+
responses:
34+
200:
35+
description: OK
36+
/pay:
37+
post:
38+
tags:
39+
- tag3
40+
summary: Make Payment
41+
description: Froyo's the best!
42+
responses:
43+
200:
44+
description: OK
45+
46+
tags:
47+
- name: tag1
48+
description: Everything about your restaurant
49+
x-displayName: Tag 1
50+
- name: tag2
51+
description: Tag 2 description
52+
x-displayName: Tag 2
53+
- name: tag3
54+
description: Tag 3 description
55+
x-displayName: Tag 3
56+
57+
x-tagGroups:
58+
- name: Tag 1 & 2
59+
tags:
60+
- tag1
61+
- tag2
62+
- name: Trinity
63+
tags:
64+
- tag1
65+
- tag2
66+
- tag3
67+
- name: Last Two
68+
tags:
69+
- tag2
70+
- tag3

‎demo/examples/petstore.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -996,6 +996,7 @@ components:
996996
description: Average amount of honey produced per day in ounces
997997
example: 3.14
998998
multipleOf: .01
999+
default: 0
9991000
required:
10001001
- honeyPerDay
10011002
Id:

‎demo/sidebars.ts

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,16 @@ const sidebars: SidebarsConfig = {
108108
},
109109
],
110110
},
111+
{
112+
type: "category",
113+
label: "Restaurant",
114+
link: {
115+
type: "generated-index",
116+
title: "Restaurant API",
117+
slug: "/category/restaurant-api",
118+
},
119+
items: require("./docs/restaurant/sidebar.js"),
120+
},
111121
],
112122
"petstore-2.0.0": [
113123
{

‎packages/docusaurus-plugin-openapi-docs/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
159159
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
160160
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
161161
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
162+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |
162163

163164
`sidebarOptions` can be configured with the following options:
164165

0 commit comments

Comments
 (0)