Skip to content

Commit d03859d

Browse files
sserratasserrata
authored
Prepare release v3.0.0 (#868)
* Prepare release v3.0.0 * update docs
1 parent 3675c4e commit d03859d

File tree

8 files changed

+306
-302
lines changed

8 files changed

+306
-302
lines changed

‎CHANGELOG.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,41 @@
1+
## 3.0.0 (Jul 3, 2024)
2+
3+
First official v3 release!
4+
5+
- Added support for Docusaurus v3.0.1 - v3.4.0 (and hopefully beyond)
6+
- Complete feature parity with v2.2.0 including bug fixes
7+
8+
Other enhancements and bug fixes
9+
10+
- Support absolute or relative downloadUrl ([#865](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/865))
11+
- fix typo in attribute ([#864](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/864))
12+
- uncomment version dropdown styles ([#863](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/863))
13+
- Support flexible code snippet ordering and options ([#862](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/862))
14+
- migrate back to canonical postman deps ([#860](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/860))
15+
- Support custom downloadUrl for versions ([#859](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/859))
16+
- [V3] Fix tagGroup display when showSchemas is configured ([#852](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/852))
17+
- check to avoid tagGroup config before concat operation, api, schemas ([#853](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/853))
18+
- handle various additionalProperties cases ([#803](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/803))
19+
- cleanup legacy ApiDemoPanel component
20+
- cleanup legacy docusaurus config
21+
- upgrade to docusaurus 3.4.0 ([#850](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/850))
22+
- support empty object schema type ([#849](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/849))
23+
- ensure readOnly/writeOnly are evaluated first ([#848](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/848))
24+
- transparent bg color when showing placeholder ([#847](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/847))
25+
- Bug/set accept ([#846](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/846))
26+
- Implement the `x-tags` extension for schema objects ([#837](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/837))
27+
- fix col row padding footer&pagination ([#810](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/810))
28+
- Update index.tsx ([#839](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/839))
29+
- fix: markdown table within the description attribute cannot be rendered correctly ([#831](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/831))
30+
- upgrade demo to docusaurus 3.3.2 ([#822](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/822))
31+
- add missing types and cast ref to LegacyRef ([#818](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/818))
32+
- Add option to disable frontmatter api prop compression ([#800](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/800))
33+
- preventing to send form onClick left/right arrows in SchemaTabs component ([#796](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/796))
34+
- Ensure sidebars.ts and schemas are properly cleaned ([#817](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/817))
35+
- changed theme and plugin to headings ([#786](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/786))
36+
- Allow custom plugin to render ([#784](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/784))
37+
- Remove scrollbar width for Tab components ([#785](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/785))
38+
139
## 3.0.0-beta.10 (Mar 25, 2024)
240

341
High level enhancements

‎README.md‎

Lines changed: 47 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<div align="center">
88

9-
OpenAPI plugin for generating API reference docs in Docusaurus v2.
9+
OpenAPI plugin for generating API reference docs in Docusaurus v3.
1010

1111
<img src="https://img.shields.io/badge/dynamic/json?style=for-the-badge&logo=meta&color=blueviolet&label=Docusaurus&query=dependencies%5B%22%40docusaurus%2Fcore%22%5D&url=https%3A%2F%2Fraw.githubusercontent.com%2FPaloAltoNetworks%2Fdocusaurus-openapi-docs%2Fmain%2Fdemo%2Fpackage.json" />
1212
<br/><br/>
@@ -28,11 +28,11 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2.
2828

2929
## Overview
3030

31-
The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs by setting `docItemComponent` to `@theme/ApiItem`, a custom component included in the `docusaurus-theme-openapi-docs` theme.
31+
The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs when combined with the `docusaurus-theme-openapi-docs` theme.
3232

3333
Key Features:
3434

35-
- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.0.
35+
- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
3636
- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
3737
- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
3838
- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
@@ -41,16 +41,16 @@ Key Features:
4141

4242
| Docusaurus OpenAPI Docs | Docusaurus |
4343
| ----------------------- | --------------- |
44-
| 3.0.0-beta.x (beta) | `3.0.1 - 3.1.1` |
45-
| 2.0.x (current) | `2.4.1 - 2.4.3` |
44+
| 3.0.0 (current) | `3.0.1 - 3.4.0` |
45+
| 2.2.0 (legacy) | `2.4.1 - 2.4.3` |
4646
| 1.7.3 (legacy) | `2.0.1 - 2.2.0` |
4747

4848
## Bootstrapping from Template (new Docusaurus site)
4949

50-
Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
50+
Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
5151

5252
```bash
53-
npx create-docusaurus@2.4.3 my-website --package-manager yarn
53+
npx create-docusaurus@3.4.0 my-website --package-manager yarn
5454
```
5555

5656
> When prompted to select a template choose `Git repository`.
@@ -61,77 +61,75 @@ Template Repository URL:
6161
https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
6262
```
6363

64-
> When asked how the template repo should be cloned choose "copy" (unless you know better).
64+
> When asked how the template repo should be cloned choose "copy".
6565
6666
```bash
6767
cd my-website
6868
yarn start
6969
```
7070

71+
If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API!
72+
7173
## Installation (existing Docusaurus site)
7274

73-
Plugin:
75+
> 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.
76+
77+
### Plugin
7478

7579
```bash
7680
yarn add docusaurus-plugin-openapi-docs
7781
```
7882

79-
Theme:
83+
### Theme
8084

8185
```bash
8286
yarn add docusaurus-theme-openapi-docs
8387
```
8488

85-
## Configuring `docusaurus.config.js` (Plugin and theme usage)
89+
## Configuring `docusaurus.config.ts` (Plugin and theme usage)
8690

87-
Here is an example of properly configuring `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
91+
Here is an example of properly configuring `docusaurus.config.ts` for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
8892

89-
```js
90-
// docusaurus.config.js
93+
> Note: Instructions may differ slightly for sites that haven't migrated to typescript.
94+
95+
```typescript
96+
// docusaurus.config.ts
97+
// note that parts of the complete config were left out for brevity
98+
import type * as Preset from "@docusaurus/preset-classic";
99+
import type { Config } from "@docusaurus/types";
100+
import type * as Plugin from "@docusaurus/types/src/plugin";
101+
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
91102

92103
{
93104
presets: [
94105
[
95106
"classic",
96-
/** @type {import('@docusaurus/preset-classic').Options} */
97-
({
107+
{
98108
docs: {
99-
sidebarPath: require.resolve("./sidebars.js"),
100-
editUrl:
101-
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
102-
docLayoutComponent: "@theme/DocPage",
103-
docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
104-
},
105-
blog: {
106-
showReadingTime: true,
107-
editUrl:
108-
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
109+
sidebarPath: "./sidebars.ts",
110+
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
109111
},
110112
theme: {
111-
customCss: require.resolve("./src/css/custom.css")
112-
}
113-
})
114-
]
113+
customCss: "./src/css/custom.css",
114+
},
115+
} satisfies Preset.Options,
116+
],
115117
],
116118

117119
plugins: [
118120
[
119121
'docusaurus-plugin-openapi-docs',
120122
{
121123
id: "api", // plugin id
122-
docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
124+
docsPluginId: "classic", // configured for preset-classic
123125
config: {
124-
petstore: { // the <id> referenced when running CLI commands
125-
specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
126-
outputDir: "api/petstore", // output directory for generated files
127-
sidebarOptions: { // optional, instructs plugin to generate sidebar.js
128-
groupPathsBy: "tag", // group sidebar items by operation "tag"
126+
petstore: {
127+
specPath: "examples/petstore.yaml",
128+
outputDir: "docs/petstore",
129+
sidebarOptions: {
130+
groupPathsBy: "tag",
129131
},
130-
},
131-
burgers: {
132-
specPath: "examples/food/burgers/openapi.yaml",
133-
outputDir: "api/food/burgers",
134-
}
132+
} satisfies OpenApiPlugin.Options,
135133
}
136134
},
137135
]
@@ -226,11 +224,12 @@ Commands:
226224
write-translations [options] [siteDir] Extract required translations of your site.
227225
write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content.
228226
docs:version <version> Tag a new docs version
229-
gen-api-docs <id> Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
230-
gen-api-docs:version <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
231-
clean-api-docs <id> Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
232-
clean-api-docs:version <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
227+
gen-api-docs [options] <id> Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
228+
gen-api-docs:version [options] <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if
233229
enabled).
230+
clean-api-docs [options] <id> Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
231+
clean-api-docs:version [options] <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts
232+
(if enabled)
234233
```
235234

236235
### Generating OpenAPI Docs
@@ -252,10 +251,10 @@ yarn docusaurus gen-api-docs <id>
252251
Example:
253252

254253
```bash
255-
yarn docusaurus gen-api-docs burgers
254+
yarn docusaurus gen-api-docs petstore
256255
```
257256

258-
> The example above will only generate API docs relative to `burgers`.
257+
> The example above will only generate API docs relative to `petstore`.
259258
260259
### Cleaning API Docs
261260

@@ -274,7 +273,7 @@ yarn docusaurus clean-api-docs <id>
274273
Example:
275274

276275
```bash
277-
yarn docusaurus clean-api-docs burgers
276+
yarn docusaurus clean-api-docs petstore
278277
```
279278

280279
> The example above will remove all API docs relative to `burgers`.

0 commit comments

Comments
 (0)