Skip to content

Commit 1fe5df5

Browse files
bourdakos1bourdakos1
authored
Prepare release v0.2.0 (#71)
1 parent b4fc51f commit 1fe5df5

9 files changed

Lines changed: 173 additions & 164 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,63 @@
1+
## 0.2.0 (Dec 4, 2021)
2+
3+
### 💥 Breaking Changes
4+
5+
The plugin option `openapiPath` has been renamed to `path` and no longer needs to be wrapped in `require.resolve`.
6+
7+
As recomended my the [Docusaurus documentation](https://docusaurus.io/docs/presets), the plugin `docusaurus-plugin-api` has been properly split into 3 packages:
8+
9+
- `docusaurus-preset-api`
10+
- `docusaurus-plugin-api`
11+
- `docusaurus-theme-api`
12+
13+
The package `docusaurus-plugin-api` will no longer work on it's own without `docusaurus-theme-api`. Instead, the preset `docusaurus-preset-api` can be used on it's own and act as a drop-in replacement for `@docusaurus/preset-classic`.
14+
15+
Example usage:
16+
17+
```diff
18+
// docusaurus.config.js
19+
20+
const config = {
21+
- plugins: [
22+
- [
23+
- "docusaurus-plugin-openapi",
24+
- {
25+
- openapiPath: require.resolve("./examples/openapi.json"),
26+
- },
27+
- ],
28+
- ],
29+
30+
presets: [
31+
[
32+
- "@docusaurus/preset-classic",
33+
+ "docusaurus-preset-openapi",
34+
{
35+
+ api: {
36+
+ path: "examples/openapi.json",
37+
+ }
38+
docs: {
39+
// doc options ...
40+
},
41+
blog: {
42+
// blog options ...
43+
},
44+
theme: {
45+
customCss: require.resolve("./src/css/custom.css"),
46+
},
47+
},
48+
],
49+
],
50+
}
51+
```
52+
53+
Other enhancements and bug fixes
54+
55+
- Fix multi plugin bug ([#69](https://github.com/cloud-annotations/docusaurus-plugin-openapi/pull/69))
56+
- Add yaml support ([#68](https://github.com/cloud-annotations/docusaurus-plugin-openapi/pull/68))
57+
- Generate markdown for full page ([#65](https://github.com/cloud-annotations/docusaurus-plugin-openapi/pull/65))
58+
- Refactor plugin into separate packages ([#64](https://github.com/cloud-annotations/docusaurus-plugin-openapi/pull/64))
59+
- Update documentation ([#63](https://github.com/cloud-annotations/docusaurus-plugin-openapi/pull/63))
60+
161
## 0.1.1 (Nov 24, 2021)
262

363
Enhancements and bug fixes

‎README-dev.md‎

Lines changed: 0 additions & 121 deletions
This file was deleted.

‎README.md‎

Lines changed: 101 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,123 @@
1-
# Docusaurus Plugin OpenAPI (WIP)
1+
# Docusaurus OpenAPI (beta)
22

33
![](https://user-images.githubusercontent.com/4212769/85324376-b9e3d900-b497-11ea-9765-c42a8ad1ff61.png)
44

5-
Install the plugin in your docusaurus project:
5+
> 💥 0.1.0 -> 0.2.0 [breaking changes](./CHANGELOG.md#020-dec-4-2021)
66
7-
```
8-
yarn add docusaurus-plugin-openapi
7+
## Preset usage
8+
9+
Install the preset in your docusaurus project by running:
10+
11+
```sh
12+
// with npm
13+
npm install docusaurus-preset-openapi
14+
15+
// with yarn
16+
yarn add docusaurus-preset-openapi
917
```
1018

11-
Add it as a plugin to `docusaurus.config.js`:
19+
The OpenAPI preset can be used as a drop-in replacement to `@docusaurus/preset-classic`:
1220

1321
```js
14-
plugins: [
15-
[
16-
"docusaurus-plugin-openapi",
17-
{
18-
openapiPath: require.resolve("./openapi.json"),
19-
},
22+
/* docusaurus.config.js */
23+
24+
{
25+
presets: [
26+
[
27+
"docusaurus-preset-openapi",
28+
{
29+
// ... options
30+
},
31+
],
2032
],
21-
];
33+
}
2234
```
2335

24-
Add it as a item in `docusaurus.config.js` to `themeConfig.navbar.items`:
36+
The default preset options will expose a route, `/api`, and look for an OpenAPI definition at `./openapi.json`.
37+
38+
To explictly configure this, add an `api` stanza as follows:
2539

2640
```js
27-
{ to: "/api", label: "API", position: "left" }
41+
/* docusaurus.config.js */
42+
43+
{
44+
presets: [
45+
[
46+
"docusaurus-preset-openapi",
47+
{
48+
api: {
49+
path: 'openapi.json',
50+
routeBasePath: 'api',
51+
},
52+
// ... other options
53+
},
54+
],
55+
],
56+
}
2857
```
2958

30-
For more than one OpenAPI definition, add them as multiple plugins to `docusaurus.config.js`:
59+
To add a link to the API page, add a new item to the navbar by updating `themeConfig.navbar.items`:
3160

3261
```js
33-
plugins: [
34-
[
35-
"docusaurus-plugin-openapi",
36-
{
37-
id: "plugin-1",
38-
openapiPath: require.resolve("./openapi1.json"),
39-
routeBasePath: "cars",
62+
/* docusaurus.config.js */
63+
64+
{
65+
themeConfig: {
66+
navbar: {
67+
items: [
68+
// ... other items
69+
{ to: "/api", label: "API", position: "left" },
70+
// ... other items
71+
],
4072
},
73+
},
74+
}
75+
```
76+
77+
## Multiple OpenAPI Definitions
78+
79+
To have more than one OpenAPI pages, add additional OpenAPI plugin instances:
80+
81+
```js
82+
/* docusaurus.config.js */
83+
84+
{
85+
presets: [
86+
[
87+
'docusaurus-preset-openapi',
88+
{
89+
api: {
90+
// id: 'cars', // omitted => default instance
91+
path: 'cars/openapi.json',
92+
routeBasePath: 'cars',
93+
// ... other options
94+
},
95+
},
96+
],
4197
],
42-
[
43-
"docusaurus-plugin-openapi",
44-
{
45-
id: "plugin-2",
46-
openapiPath: require.resolve("./openapi2.json"),
47-
routeBasePath: "bikes",
48-
},
98+
plugins: [
99+
[
100+
'docusaurus-plugin-openapi',
101+
{
102+
id: 'trains',
103+
path: 'trains/openapi.json',
104+
routeBasePath: 'trains',
105+
// ... other options
106+
},
107+
],
108+
[
109+
'docusaurus-plugin-openapi',
110+
{
111+
id: 'bikes',
112+
path: 'bikes/openapi.json',
113+
routeBasePath: 'bikes',
114+
// ... other options
115+
},
116+
],
49117
],
50-
];
118+
}
51119
```
52120

53-
This will be resolved at /cars and /bikes endpoints respectively.
121+
This will create routes for `/cars`, `/trains` and `/bikes`.
122+
123+
> **Note:** One instance of the plugin is included in the preset. All additional plugin instances will require an `id`.

‎demo/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "demo",
3-
"version": "0.1.1",
3+
"version": "0.2.0",
44
"private": true,
55
"scripts": {
66
"docusaurus": "docusaurus",
@@ -18,7 +18,7 @@
1818
"@mdx-js/react": "^1.6.21",
1919
"@svgr/webpack": "^5.5.0",
2020
"clsx": "^1.1.1",
21-
"docusaurus-preset-openapi": "^0.1.1",
21+
"docusaurus-preset-openapi": "^0.2.0",
2222
"file-loader": "^6.2.0",
2323
"prism-react-renderer": "^1.2.1",
2424
"react": "^17.0.1",

‎lerna.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "0.1.1",
2+
"version": "0.2.0",
33
"npmClient": "yarn",
44
"useWorkspaces": true
55
}

‎packages/docusaurus-plugin-openapi/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "docusaurus-plugin-openapi",
33
"description": "OpenAPI plugin for Docusaurus.",
4-
"version": "0.1.1",
4+
"version": "0.2.0",
55
"license": "MIT",
66
"publishConfig": {
77
"access": "public"

‎packages/docusaurus-preset-openapi/package.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "docusaurus-preset-openapi",
33
"description": "OpenAPI preset for Docusaurus.",
4-
"version": "0.1.1",
4+
"version": "0.2.0",
55
"license": "MIT",
66
"publishConfig": {
77
"access": "public"
@@ -32,8 +32,8 @@
3232
"@docusaurus/preset-classic": "2.0.0-beta.9",
3333
"@docusaurus/theme-classic": "2.0.0-beta.9",
3434
"@docusaurus/theme-search-algolia": "2.0.0-beta.9",
35-
"docusaurus-plugin-openapi": "0.1.1",
36-
"docusaurus-theme-openapi": "0.1.1"
35+
"docusaurus-plugin-openapi": "^0.2.0",
36+
"docusaurus-theme-openapi": "^0.2.0"
3737
},
3838
"peerDependencies": {
3939
"react": "^16.8.4 || ^17.0.0",

0 commit comments

Comments
 (0)