diff --git a/.github/workflows/canary-beta-release.yml b/.github/workflows/canary-beta-release.yml
index 6762f3e25..abac23ecd 100644
--- a/.github/workflows/canary-beta-release.yml
+++ b/.github/workflows/canary-beta-release.yml
@@ -3,7 +3,7 @@ name: Canary Beta Release
on:
push:
branches:
- - v2.0.0
+ - v3.0.0
paths:
- packages/**
@@ -14,7 +14,7 @@ jobs:
publish-canary:
name: Publish Canary Beta
runs-on: ubuntu-latest
- if: ${{ github.repository == 'PaloAltoNetworks/docusaurus-openapi-docs' && github.ref == 'refs/heads/v2.0.0' && github.event_name == 'push' }}
+ if: ${{ github.repository == 'PaloAltoNetworks/docusaurus-openapi-docs' && github.ref == 'refs/heads/v3.0.0' && github.event_name == 'push' }}
steps:
- name: Checkout
uses: actions/checkout@v3
@@ -30,7 +30,7 @@ jobs:
git config --global user.name "Steven Serrata"
git config --global user.email "sserrata@paloaltonetworks.com"
git fetch
- git checkout v2.0.0
+ git checkout v3.0.0
echo "//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}" >> .npmrc
env:
NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index 8a42c4cf0..34cd3b01a 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -2,7 +2,7 @@ name: "CodeQL"
on:
push:
- branches: [main, v2.0.0]
+ branches: [main, v3.0.0]
jobs:
analyze:
diff --git a/.github/workflows/deploy-preview.yml b/.github/workflows/deploy-preview.yml
index b0454c33e..569c57acb 100644
--- a/.github/workflows/deploy-preview.yml
+++ b/.github/workflows/deploy-preview.yml
@@ -2,7 +2,7 @@ name: "Deploy Preview"
on:
pull_request_target:
- branches: [main, v2.0.0]
+ branches: [main, v3.0.0]
jobs:
precheck:
diff --git a/.github/workflows/pr-title-check.yaml b/.github/workflows/pr-title-check.yaml
index 8c647198a..a7fbb042b 100644
--- a/.github/workflows/pr-title-check.yaml
+++ b/.github/workflows/pr-title-check.yaml
@@ -4,7 +4,7 @@ on:
pull_request:
branches:
- main
- - v2.0.0
+ - v3.0.0
types:
- opened
- synchronize
diff --git a/.github/workflows/release-beta.yaml b/.github/workflows/release-beta.yaml
index 5903a8d48..68084aa56 100644
--- a/.github/workflows/release-beta.yaml
+++ b/.github/workflows/release-beta.yaml
@@ -3,7 +3,7 @@ name: Release Beta
on:
push:
branches:
- - v2.0.0
+ - v3.0.0
env:
FORCE_COLOR: true
diff --git a/.github/workflows/validate.yaml b/.github/workflows/validate.yaml
index ea5fdf9b9..95690664e 100644
--- a/.github/workflows/validate.yaml
+++ b/.github/workflows/validate.yaml
@@ -4,7 +4,7 @@ on:
push:
branches: [main]
pull_request:
- branches: [main, v2.0.0]
+ branches: [main, v3.0.0]
env:
FORCE_COLOR: true
diff --git a/.gitignore b/.gitignore
index bc9d2e278..10e42b734 100644
--- a/.gitignore
+++ b/.gitignore
@@ -137,6 +137,8 @@ dist
demo/**/*.api.mdx
demo/**/*.info.mdx
demo/**/*.tag.mdx
-demo/**/sidebar.js
+demo/**/*.schema.mdx
+demo/**/sidebar.ts
demo/**/versions.json
+.idea
diff --git a/.prettierrc.json b/.prettierrc.json
index 0967ef424..757fd64ca 100644
--- a/.prettierrc.json
+++ b/.prettierrc.json
@@ -1 +1,3 @@
-{}
+{
+ "trailingComma": "es5"
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 92660fde6..af58e836c 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -4,21 +4,26 @@
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
- "source.fixAll.eslint": true
+ "source.fixAll.eslint": "explicit"
}
},
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
- "source.fixAll.eslint": true
+ "source.fixAll.eslint": "explicit"
}
},
"[typescriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
- "source.fixAll.eslint": true
+ "source.fixAll.eslint": "explicit"
+ }
+ },
+ "[javascript][typescript][typescriptreact]": {
+ "editor.codeActionsOnSave": {
+ "source.fixAll.eslint": "explicit"
}
}
}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ea0eebba..b20f9da73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,136 @@
+## 3.0.0-beta.10 (Mar 25, 2024)
+
+High level enhancements
+
+- Various bugfixes
+
+Other enhancements and bug fixes
+
+- use inline to remove p tag ([#779](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/779))
+- upgrade lerna to 8.1.2 ([#778](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/778))
+
+## 3.0.0-beta.9 (Mar 22, 2024)
+
+High level enhancements
+
+- bugfix
+
+Other enhancements and bug fixes
+
+- ensure correct eval of required properties with allOf ([#771](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/771))
+
+## 3.0.0-beta.8 (Mar 21, 2024)
+
+High level enhancements
+
+- Various bug fixes
+
+Other enhancements and bug fixes
+
+- Fix allOf schema qualifier and type ([#766](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/766))
+- Ensure qualifiers are rendered for polymorphic/primitive properties ([#765](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/765))
+- uncomment line preventing grouping by operation tags ([#764](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/764))
+- ensure resize observer is calculated once per frame to avoid loops ([#763](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/763))
+
+## 3.0.0-beta.7 (Mar 20, 2024)
+
+High level enhancements
+
+- Improve OpenAPI 3.1 support
+
+Other enhancements and bug fixes
+
+- fix import/eslint errors
+- [bugfix] Ensure 0 and false are guarded correctly and add deprecated support to params ([#754](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/754))
+- Upgrade OpenAPI parsers ([#749](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/749))
+
+## 3.0.0-beta.6 (Mar 15, 2024)
+
+High level enhancements
+
+- Improve x-codeSamples support
+- Add support for generating schemas
+- Add support for using x-tagGroup to generate sidebar
+
+Other enhancements and bug fixes
+
+- upgrade prettier
+- V2 feature parity ([#742](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/742))
+- upgrade to docusaurus 3.1.1 ([#740](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/740))
+- fix: markdown pages heading creation ([#716](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/716))
+- Fix x-codeSamples load when switching language tabs in V3 ([#706](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/706))
+
+## 3.0.0-beta.5 (Jan 18, 2024)
+
+High level enhancements
+
+- Add support for x-CodeSamples
+- Add callbacks support
+- Add markdown support to example/examples summary
+- Remove deprecated node packages from generated snippets
+
+Other enhancements and bug fixes
+
+- Add support to x-codeSamples in v3 ([#701](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/701))
+- Add Callbacks Support to V3 ([#700](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/700))
+- Remove deprecated node packages ([#699](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/699))
+- Add markdown support to example summary ([#690](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/690))
+
+## 3.0.0-beta.4 (Jan 5, 2024)
+
+High level enhancements
+
+- Improve Typescript coverage of theme components
+- Fix syntax highlighting
+
+Other enhancements and bug fixes
+
+- [V3] Refactor theme package to Typescript ([#684](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/684))
+- Prepare release v3.0.0-beta.3 ([#682](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/682))
+- upgrade prettier
+- install prettier plugin ([#681](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/681))
+- [V3] Improved Docusaurus 3 compatibility ([#677](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/677))
+- Prepare release v3.0.0-beta.2 ([#668](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/668))
+- Port v2 changes/fixes into v3 ([#667](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/667))
+
+## 3.0.0-beta.3 (Dec 13, 2023)
+
+High level enhancements
+
+- Improve Docusaurus 3 compatibility
+- Upgrade to Docusaurus 3.0.1
+
+Other enhancements and bug fixes
+
+- upgrade prettier
+- install prettier plugin ([#681](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/681))
+- [V3] Improved Docusaurus 3 compatibility ([#677](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/677))
+- Prepare release v3.0.0-beta.2 ([#668](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/668))
+- Port v2 changes/fixes into v3 ([#667](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/667))
+
+## 3.0.0-beta.2 (Dec 1, 2023)
+
+High level enhancements
+
+- Port recent v2 changes/fixes into v3 ([#667](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/667))
+
+## 3.0.0-beta.1 (Nov 17, 2023)
+
+High level enhancements
+
+- First beta release for v3.0.0
+
+Other enhancements and bug fixes
+
+- update v2.0.0 refs to v3.0.0
+- update createSchema snapshot
+- support v3.0.0 canary releases
+- bump version to 3.0.0-beta.0
+- re-enable all API docs
+- convert contact info to markdown, update lessThan regex and escape description
+- initial refactor
+- Update README.md
+
## 2.0.0 (Nov 13, 2023)
High level enhancements
diff --git a/README.md b/README.md
index 8e70c5744..c7b689d66 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,7 @@ Key Features:
| Docusaurus OpenAPI Docs | Docusaurus |
| ----------------------- | --------------- |
+| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` |
| 2.0.x (current) | `2.4.1 - 2.4.3` |
| 1.7.3 (legacy) | `2.0.1 - 2.2.0` |
@@ -145,10 +146,11 @@ Here is an example of properly configuring `docusaurus.config.js` file for `docu
The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
-| Name | Type | Default | Description |
-| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id` | `string` | `null` | A unique plugin ID. |
-| `docsPluginId` | `string` | `null` | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
+| Name | Type | Default | Description |
+| -------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | `string` | `null` | A unique plugin ID. |
+| `docsPlugin` | `string` | `@docusaurus/plugin-content-docs` | The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by `docsPluginId` is a `preset`). |
+| `docsPluginId` | `string` | `null` | The plugin ID associated with the `preset` or configured `docsPlugin` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
### config
@@ -169,12 +171,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.
The supported options are as follows:
`tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description.
`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).
`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. |
@@ -197,11 +200,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.
**Function type:** `(pageData: ApiPageMetadata) => string` |
-| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.
**Function type:** `(pageData: InfoPageMetadata) => string` |
-| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.
**Function type:** `(pageData: TagPageMetadata) => string` |
+| Name | Type | Default | Description |
+| -------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.
**Function type:** `(pageData: ApiPageMetadata) => string` |
+| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.
**Function type:** `(pageData: InfoPageMetadata) => string` |
+| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.
**Function type:** `(pageData: TagPageMetadata) => string` |
+| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.
**Function type:** `(pageData: SchemaPageMetadata) => string` |
## CLI Usage
diff --git a/demo/docs/customization/languagetabs.md b/demo/docs/customization/languagetabs.mdx
similarity index 98%
rename from demo/docs/customization/languagetabs.md
rename to demo/docs/customization/languagetabs.mdx
index 0d9de3d36..b40c8cdca 100644
--- a/demo/docs/customization/languagetabs.md
+++ b/demo/docs/customization/languagetabs.mdx
@@ -15,7 +15,7 @@ The Docusaurus OpenAPI docs plugin comes with support for 8 languages which you
| `curl` | bash | `curl`\* |
| `python` | python | `requests`\*, `http.client` |
| `go` | go | `native`\* |
-| `nodejs` | javascript | `axios`\*, `native`, `requests`, `unirest` |
+| `nodejs` | javascript | `axios`\*, `native` |
| `ruby` | ruby | `net::http`\* |
| `csharp` | csharp | `restsharp`\*, `httpclient` |
| `php` | php | `curl`\*, `guzzle`, `pecl_http`, `http_request2` |
diff --git a/demo/docs/customization/styling.md b/demo/docs/customization/styling.mdx
similarity index 80%
rename from demo/docs/customization/styling.md
rename to demo/docs/customization/styling.mdx
index 7a3c34c60..6a43a5e22 100644
--- a/demo/docs/customization/styling.md
+++ b/demo/docs/customization/styling.mdx
@@ -18,13 +18,15 @@ The demo site uses the following CSS to add coloured labels to each request incl
```css
/* API Menu Items */
-.api-method > .menu__link {
+.api-method > .menu__link,
+.schema > .menu__link {
align-items: center;
justify-content: start;
}
-.api-method > .menu__link::before {
- width: 50px;
+.api-method > .menu__link::before,
+.schema > .menu__link::before {
+ width: 55px;
height: 20px;
font-size: 12px;
line-height: 20px;
@@ -68,6 +70,16 @@ The demo site uses the following CSS to add coloured labels to each request incl
content: "head";
background-color: var(--ifm-color-secondary-darkest);
}
+
+.event > .menu__link::before {
+ content: "event";
+ background-color: var(--ifm-color-secondary-darkest);
+}
+
+.schema > .menu__link::before {
+ content: "schema";
+ background-color: var(--ifm-color-secondary-darkest);
+}
```
## Alternative Styling
@@ -76,13 +88,15 @@ In [this issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issu
```css
/* Sidebar Method labels */
-.api-method > .menu__link {
+.api-method > .menu__link,
+.schema > .menu__link {
align-items: center;
justify-content: start;
}
-.api-method > .menu__link::before {
- width: 50px;
+.api-method > .menu__link::before,
+.schema > .menu__link::before {
+ width: 55px;
height: 20px;
font-size: 12px;
line-height: 20px;
@@ -137,4 +151,18 @@ In [this issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issu
color: var(--ifm-color-secondary-contrast-foreground);
border-color: var(--ifm-color-secondary-dark);
}
+
+.event > .menu__link::before {
+ content: "event";
+ background-color: var(--ifm-color-secondary-contrast-background);
+ color: var(--ifm-color-secondary-contrast-foreground);
+ border-color: var(--ifm-color-secondary-dark);
+}
+
+.schema > .menu__link::before {
+ content: "schema";
+ background-color: var(--ifm-color-secondary-contrast-background);
+ color: var(--ifm-color-secondary-contrast-foreground);
+ border-color: var(--ifm-color-secondary-dark);
+}
```
diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx
index e5d43e55d..1143ae386 100644
--- a/demo/docs/intro.mdx
+++ b/demo/docs/intro.mdx
@@ -58,6 +58,7 @@ Key Features:
| Docusaurus OpenAPI Docs | Docusaurus |
| ----------------------- | --------------- |
+| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` |
| 2.0.x (current) | `2.4.1 - 2.4.3` |
| 1.7.3 (legacy) | `2.0.1 - 2.2.0` |
@@ -95,13 +96,13 @@ yarn start
Both the plugin and theme are currently designed to pair with a specific Docusaurus release. The Docusaurus badge in the `README.md` and at the top of this page will always reflect the current compatible versions.
:::
-Plugin:
+### Plugin
```bash
yarn add docusaurus-plugin-openapi-docs
```
-Theme:
+### Theme
```bash
yarn add docusaurus-theme-openapi-docs
@@ -336,6 +337,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
@@ -373,11 +375,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.
**Function type:** `(pageData: ApiPageMetadata) => string` |
-| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.
**Function type:** `(pageData: InfoPageMetadata) => string` |
-| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.
**Function type:** `(pageData: TagPageMetadata) => string` |
+| Name | Type | Default | Description |
+| ------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------|
+| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.
**Function type:** `(pageData: ApiPageMetadata) => string` |
+| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.
**Function type:** `(pageData: InfoPageMetadata) => string` |
+| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.
**Function type:** `(pageData: TagPageMetadata) => string` |
+| `createSchemaPageMD`| `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.