Skip to content

V2 feature parity #742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 15, 2024
Merged

V2 feature parity #742

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
99f0b5c
feat: implement x-tagGroup feature (#737)
bencagri Mar 15, 2024
2c7ccd6
cleanup missing types, dup imports and add restaurant example
sserrata Mar 15, 2024
104fb7c
fix: Guard only undefined and empty strings (#725)
ImFlog Mar 12, 2024
14bdb6a
Conditional display of header Request (#719)
chranmat Mar 12, 2024
0a03fa2
update lock file
sserrata Mar 15, 2024
5434b4f
feat: Implement schema pages behind a config option `showSchemas` (#736)
MarcL01 Mar 12, 2024
4be6e35
address linter errors
sserrata Mar 15, 2024
96c70b4
enable schemas for petstore
sserrata Mar 15, 2024
f662fa1
update lock file
sserrata Mar 15, 2024
5de28cb
add missing heading import
sserrata Mar 15, 2024
b11d101
address linter errors
sserrata Mar 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,8 @@ dist
demo/**/*.api.mdx
demo/**/*.info.mdx
demo/**/*.tag.mdx
demo/**/*.schema.mdx
demo/**/sidebar.ts
demo/**/versions.json

.idea
14 changes: 8 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,13 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
| `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. |
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |

`sidebarOptions` can be configured with the following options:

| Name | Type | Default | Description |
| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`. |
| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. |
| `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. |
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
Expand All @@ -197,11 +198,12 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following

`markdownGenerators` can be configured with the following options:

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

## CLI Usage

Expand Down
12 changes: 7 additions & 5 deletions demo/docs/intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
| `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. |
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |

### sidebarOptions

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

`markdownGenerators` can be configured with the following options:

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

:::info NOTE
If a config option is not provided, its default markdown generator will be used.
Expand Down
6 changes: 6 additions & 0 deletions demo/docs/sidebars.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,12 @@ For greater control, you also have the option of constructing the sidebar object

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.

### Grouping by TagGroup

The OpenAPI docs plugin provides out-of-the-box support for grouping paths by "tagGroup".
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.
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.

### Category Links

Docusaurus now supports the ability to designate or customize what page gets displayed when a category is clicked.
Expand Down
8 changes: 8 additions & 0 deletions demo/docusaurus.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,7 @@ const config: Config = {
downloadUrl:
"https://raw.githubusercontent.com/PaloAltoNetworks/docusaurus-openapi-docs/main/demo/examples/petstore.yaml",
hideSendButton: false,
showSchemas: true,
} satisfies OpenApiPlugin.Options,
cos: {
specPath: "examples/openapi-cos.json",
Expand All @@ -259,6 +260,13 @@ const config: Config = {
specPath: "examples/food/yogurtstore/openapi.yaml",
outputDir: "docs/food/yogurtstore",
} satisfies OpenApiPlugin.Options,
restaurant: {
specPath: "examples/food/restaurant/openapi.yaml",
outputDir: "docs/restaurant",
sidebarOptions: {
groupPathsBy: "tagGroup",
},
} satisfies OpenApiPlugin.Options,
} satisfies Plugin.PluginOptions,
},
],
Expand Down
4 changes: 4 additions & 0 deletions demo/examples/food/restaurant/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Restaurant",
"collapsed": true
}
70 changes: 70 additions & 0 deletions demo/examples/food/restaurant/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
openapi: 3.0.3
info:
title: Restaurant Example
version: 1.0.0
description: Sample description.
paths:
/menu:
get:
tags:
- tag1
summary: Get Menu
description: Froyo's the best!
responses:
200:
description: OK
/products:
get:
tags:
- tag1
- tag2
summary: List All Products
description: Froyo's the best!
responses:
200:
description: OK
/drinks:
get:
tags:
- tag1
- tag2
summary: List All Drinks
description: Froyo's the best!
responses:
200:
description: OK
/pay:
post:
tags:
- tag3
summary: Make Payment
description: Froyo's the best!
responses:
200:
description: OK

tags:
- name: tag1
description: Everything about your restaurant
x-displayName: Tag 1
- name: tag2
description: Tag 2 description
x-displayName: Tag 2
- name: tag3
description: Tag 3 description
x-displayName: Tag 3

x-tagGroups:
- name: Tag 1 & 2
tags:
- tag1
- tag2
- name: Trinity
tags:
- tag1
- tag2
- tag3
- name: Last Two
tags:
- tag2
- tag3
1 change: 1 addition & 0 deletions demo/examples/petstore.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -996,6 +996,7 @@ components:
description: Average amount of honey produced per day in ounces
example: 3.14
multipleOf: .01
default: 0
required:
- honeyPerDay
Id:
Expand Down
10 changes: 10 additions & 0 deletions demo/sidebars.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,16 @@ const sidebars: SidebarsConfig = {
},
],
},
{
type: "category",
label: "Restaurant",
link: {
type: "generated-index",
title: "Restaurant API",
slug: "/category/restaurant-api",
},
items: require("./docs/restaurant/sidebar.js"),
},
],
"petstore-2.0.0": [
{
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-openapi-docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
| `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. |
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar. |

`sidebarOptions` can be configured with the following options:

Expand Down
Loading