[V3] OpenAPI 3.0 Preview

.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 }}

.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:

.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:

.github/workflows/pr-title-check.yaml

@@ -4,7 +4,7 @@ on:
   pull_request:
     branches:
       - main
-      - v2.0.0
+      - v3.0.0
     types:
       - opened
       - synchronize

.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

.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

.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

.prettierrc.json

@@ -1 +1,3 @@
-{}
+{
+  "trailingComma": "es5"
+}

.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"
     }
   }
 }

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

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. <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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -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.<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
 

demo/docs/customization/languagetabs.md → 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` |