You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Install the preset in your docusaurus project by running:
33
+
> Coming from `v0.1.0`? See the [migration guide](https://github.com/cloud-annotations/docusaurus-plugin-openapi/releases/tag/v0.2.0).
30
34
31
-
```sh
32
-
// with npm
33
-
npm install docusaurus-preset-openapi
35
+
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher)_
36
+
37
+
Then open [http://localhost:3000/](http://localhost:3000/) to see your site.<br>
38
+
When you’re ready to deploy to production, create a minified bundle with `npm run build`.
39
+
40
+
## Creating a Site
41
+
42
+
**You’ll need to have Node 14.0.0 or later version on your local development machine** (but it’s not required on the server). We recommend using the latest LTS version. You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects.
43
+
44
+
To create a new site, you may choose one of the following methods:
45
+
46
+
### npx
34
47
35
-
// with yarn
36
-
yarn add docusaurus-preset-openapi
48
+
```sh
49
+
npx create-docusaurus-openapi my-website
37
50
```
38
51
39
-
The OpenAPI preset can be used as a drop-in replacement to `@docusaurus/preset-classic`:
40
-
41
-
```js
42
-
/* docusaurus.config.js */
43
-
44
-
{
45
-
presets: [
46
-
[
47
-
"docusaurus-preset-openapi",
48
-
{
49
-
// ... options
50
-
},
51
-
],
52
-
],
53
-
}
52
+
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) is a package runner tool that comes with npm 5.2+ and higher)_
53
+
54
+
### npm
55
+
56
+
```sh
57
+
npm init docusaurus-openapi my-website
54
58
```
55
59
56
-
The default preset options will expose a route, `/api`, and look for an OpenAPI definition at `./openapi.json`.
57
-
58
-
To explictly configure this, add an `api` stanza as follows:
59
-
60
-
```js
61
-
/* docusaurus.config.js */
62
-
63
-
{
64
-
presets: [
65
-
[
66
-
"docusaurus-preset-openapi",
67
-
{
68
-
api: {
69
-
path:'openapi.json',
70
-
routeBasePath:'api',
71
-
},
72
-
// ... other options
73
-
},
74
-
],
75
-
],
76
-
}
60
+
_`npm init <initializer>` is available in npm 6+_
61
+
62
+
### Yarn
63
+
64
+
```sh
65
+
yarn create docusaurus-openapi my-website
77
66
```
78
67
79
-
To add a link to the API page, add a new item to the navbar by updating `themeConfig.navbar.items`:
80
-
81
-
```js
82
-
/* docusaurus.config.js */
83
-
84
-
{
85
-
themeConfig: {
86
-
navbar: {
87
-
items: [
88
-
// ... other items
89
-
{ to:"/api", label:"API", position:"left" },
90
-
// ... other items
91
-
],
92
-
},
93
-
},
94
-
}
68
+
_[`yarn create <starter-kit-package>`](https://yarnpkg.com/lang/en/docs/cli/create/) is available in Yarn 0.25+_
69
+
70
+
It will create a directory called `my-website` inside the current folder.<br>
71
+
Inside that directory, it will generate the initial project structure and install the transitive dependencies:
72
+
73
+
```
74
+
my-website
75
+
├── blog
76
+
│ ├── 2019-05-28-hola.md
77
+
│ ├── 2019-05-29-hello-world.md
78
+
│ └── 2020-05-30-welcome.md
79
+
├── docs
80
+
│ ├── doc1.md
81
+
│ ├── doc2.md
82
+
│ ├── doc3.md
83
+
│ └── mdx.md
84
+
├── src
85
+
│ ├── css
86
+
│ │ └── custom.css
87
+
│ └── pages
88
+
│ ├── styles.module.css
89
+
│ └── index.js
90
+
├── static
91
+
│ └── img
92
+
├── .gitignore
93
+
├── openapi.json
94
+
├── docusaurus.config.js
95
+
├── babel.config.js
96
+
├── package.json
97
+
├── sidebars.js
98
+
└── README.md
95
99
```
96
100
97
-
## Multiple OpenAPI Definitions
98
-
99
-
To have more than one OpenAPI pages, add additional OpenAPI plugin instances:
100
-
101
-
```js
102
-
/* docusaurus.config.js */
103
-
104
-
{
105
-
presets: [
106
-
[
107
-
'docusaurus-preset-openapi',
108
-
{
109
-
api: {
110
-
// id: 'cars', // omitted => default instance
111
-
path:'cars/openapi.json',
112
-
routeBasePath:'cars',
113
-
// ... other options
114
-
},
115
-
},
116
-
],
117
-
],
118
-
plugins: [
119
-
[
120
-
'docusaurus-plugin-openapi',
121
-
{
122
-
id:'trains',
123
-
path:'trains/openapi.json',
124
-
routeBasePath:'trains',
125
-
// ... other options
126
-
},
127
-
],
128
-
[
129
-
'docusaurus-plugin-openapi',
130
-
{
131
-
id:'bikes',
132
-
path:'bikes/openapi.json',
133
-
routeBasePath:'bikes',
134
-
// ... other options
135
-
},
136
-
],
137
-
],
138
-
}
101
+
-`/docusaurus.config.js` - A config file containing the site configuration. This can be used to configure the OpenAPI preset
102
+
-`/openapi.json` - The default OpenAPI defination that will be served _(path can be configured in `docusaurus.config.js`)_.
103
+
104
+
For more info see [project structure rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
105
+
106
+
Once the installation is done, you can open your project folder:
107
+
108
+
```sh
109
+
cd my-website
139
110
```
140
111
141
-
This will create routes for `/cars`, `/trains` and `/bikes`.
112
+
Inside the newly created project, you can run some built-in commands:
113
+
114
+
### `npm start` or `yarn start`
115
+
116
+
Runs the site in development mode.<br>
117
+
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
118
+
119
+
The page will automatically reload if you make changes to the code.
120
+
121
+
### `npm run build` or `yarn build`
122
+
123
+
Builds the site for production to the `build` folder.
124
+
125
+
Docusaurus is a modern static website generator that will build the website into a directory of static contents, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/).
126
+
127
+
## Popular Alternatives
128
+
129
+
Docusaurus OpenAPI is great for:
130
+
131
+
-**Static generation** All OpenAPI operations will be rendered as static pages at build time, giving many performance benefits.
132
+
-**Demo panel** Allow users to try out your API with an interactive demo panel.
133
+
-**Native Docusaurus feel** Built from scratch to work with Docusaurus.
134
+
135
+
Here are a few common cases where you might want to try something else:
142
136
143
-
> **Note:** One instance of the plugin is included in the preset. All additional plugin instances will require an `id`.
137
+
- If you need better support for more advanced OpenAPI features, check out [Redocusaurus](https://github.com/rohit-gohri/redocusaurus/). Redocusaurus embeds the much more mature OpenAPI documentation generator, [Redoc](https://github.com/Redocly/redoc), into Docusaurus as a React component.
0 commit comments