Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cloud-annotations/docusaurus-openapi
🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2.
https://github.com/cloud-annotations/docusaurus-openapi
api-documentation documentation-generator docusaurus hacktoberfest openapi openapi3 plugin react swagger
Last synced: 16 days ago
JSON representation
🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2.
- Host: GitHub
- URL: https://github.com/cloud-annotations/docusaurus-openapi
- Owner: cloud-annotations
- License: mit
- Created: 2020-06-21T18:06:52.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-26T12:25:45.000Z (about 1 month ago)
- Last Synced: 2024-05-30T22:48:00.865Z (28 days ago)
- Topics: api-documentation, documentation-generator, docusaurus, hacktoberfest, openapi, openapi3, plugin, react, swagger
- Language: TypeScript
- Homepage: https://docusaurus-openapi.netlify.app
- Size: 1.87 MB
- Stars: 476
- Watchers: 9
- Forks: 80
- Open Issues: 50
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Lists
- awesome-ccamel - cloud-annotations/docusaurus-openapi - 🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2. (TypeScript)
- my-awesome-stars - cloud-annotations/docusaurus-openapi - 🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2. (TypeScript)
README
Docusaurus OpenAPI (beta)
OpenAPI plugin for generating API reference docs in Docusaurus v2.
[](https://github.com/cloud-annotations/docusaurus-plugin-openapi/blob/HEAD/LICENSE)
[](https://www.npmjs.com/package/docusaurus-preset-openapi)
[](https://www.npmjs.com/package/docusaurus-preset-openapi)
[](https://github.com/cloud-annotations/docusaurus-plugin-openapi/actions/workflows/validate.yaml)
[](https://github.com/prettier/prettier)
[](https://www.cypress.io/)
[](https://github.com/facebook/jest)
[](https://github.com/cloud-annotations/docusaurus-plugin-openapi/blob/HEAD/CONTRIBUTING.md#pull-requests)
## Quick Overview
```sh
npx create-docusaurus-openapi my-website
cd my-website
npm start
```
> Coming from `v0.1.0`? See the [migration guide](https://github.com/cloud-annotations/docusaurus-plugin-openapi/releases/tag/v0.2.0).
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher)_
Then open [http://localhost:3000/](http://localhost:3000/) to see your site.
When you’re ready to deploy to production, create a minified bundle with `npm run build`.
## Creating a new Site
**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.
To create a new site, you may choose one of the following methods:
- ### npx
```sh
npx create-docusaurus-openapi my-website
```
_([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)_
- ### npm
```sh
npm init docusaurus-openapi my-website
```
_`npm init ` is available in npm 6+_
- ### yarn
```sh
yarn create docusaurus-openapi my-website
```
_[`yarn create `](https://yarnpkg.com/lang/en/docs/cli/create/) is available in Yarn 0.25+_
It will create a directory called `my-website` inside the current folder.
Inside that directory, it will generate the initial project structure and install the transitive dependencies:
```
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── .gitignore
├── openapi.json
├── docusaurus.config.js
├── babel.config.js
├── package.json
├── sidebars.js
└── README.md
```
- `/docusaurus.config.js` - A config file containing the site configuration. This can be used to configure the OpenAPI preset
- `/openapi.json` - The default OpenAPI definition that will be served _(path can be configured in `docusaurus.config.js`)_.
For more info see [project structure rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
Once the installation is done, you can open your project folder:
```sh
cd my-website
```
Inside the newly created project, you can run some built-in commands:
### `npm start` or `yarn start`
Runs the site in development mode.
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
The page will automatically reload if you make changes to the code.
### `npm run build` or `yarn build`
Builds the site for production to the `build` folder.
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/).
## Add to an existing Site
1. Install the dependency
```sh
npm install docusaurus-preset-openapi
```
2. Edit your `docusaurus.config.js` file to use this preset
```js
presets: [
[
"docusaurus-preset-openapi",
/** @type {import('docusaurus-preset-openapi').Options} */
{
api: {
path: "",
routeBasePath: "/api",
},
docs: {
sidebarPath: require.resolve("./sidebars.js"),
routeBasePath: "/",
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
},
],
];
```
## Popular Alternatives
Docusaurus OpenAPI is great for:
- **Static generation** All OpenAPI operations will be rendered as static pages at build time, giving many performance benefits.
- **Demo panel** Allow users to try out your API with an interactive demo panel.
- **Native Docusaurus feel** Built from scratch to work with Docusaurus.
Here are a few common cases where you might want to try something else:
- 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.
## Contributing
We encourage you to contribute to Docusaurus OpenAPI! Please check out the
[Contributing to Docusaurus OpenAPI guide](https://github.com/cloud-annotations/docusaurus-plugin-openapi/blob/main/CONTRIBUTING.md) for guidelines about how to proceed.
## License
Docusaurus OpenAPI is released under the [MIT License](https://opensource.org/licenses/MIT).