-
Notifications
You must be signed in to change notification settings - Fork 228
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #327 from rockingrohit9639/master
Added version 7.x documentation in docusaurus
- Loading branch information
Showing
33 changed files
with
1,024 additions
and
603 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
{ | ||
"root": true, | ||
"extends": [ | ||
"eslint:recommended", | ||
"plugin:import/errors", | ||
"plugin:react/recommended", | ||
"plugin:jsx-a11y/recommended", | ||
"plugin:@docusaurus/recommended", | ||
"plugin:prettier/recommended" | ||
], | ||
"plugins": ["react", "import", "jsx-a11y", "@docusaurus"], | ||
"rules": { | ||
"react/prop-types": 0, | ||
"indent": ["error", 2], | ||
"linebreak-style": 1, | ||
"quotes": ["error", "single"], | ||
"import/no-unresolved": [ | ||
2, | ||
{ "ignore": ["^@theme", "^@docusaurus", "^@site"] } | ||
] | ||
}, | ||
"parserOptions": { | ||
"ecmaVersion": 2021, | ||
"sourceType": "module", | ||
"ecmaFeatures": { | ||
"jsx": true | ||
} | ||
}, | ||
"settings": { | ||
"react": { | ||
"version": "detect" | ||
} | ||
}, | ||
"env": { | ||
"es6": true, | ||
"browser": true, | ||
"node": true | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,41 +1,98 @@ | ||
# Website | ||
# swagger-jsdoc | ||
|
||
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. | ||
This library reads your [JSDoc](https://jsdoc.app/)-annotated source code and generates an [OpenAPI (Swagger) specification](https://swagger.io/specification/). | ||
|
||
### Installation | ||
[![npm Downloads](https://img.shields.io/npm/dm/swagger-jsdoc.svg)](https://www.npmjs.com/package/swagger-jsdoc) | ||
![CI](https://github.com/Surnet/swagger-jsdoc/workflows/CI/badge.svg) | ||
|
||
``` | ||
$ yarn | ||
``` | ||
## Getting started | ||
|
||
### Local Development | ||
Imagine having API files like these: | ||
|
||
``` | ||
$ yarn start | ||
```javascript | ||
/** | ||
* @openapi | ||
* /: | ||
* get: | ||
* description: Welcome to swagger-jsdoc! | ||
* responses: | ||
* 200: | ||
* description: Returns a mysterious string. | ||
*/ | ||
app.get('/', (req, res) => { | ||
res.send('Hello World!'); | ||
}); | ||
``` | ||
|
||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. | ||
The library will take the contents of `@openapi` (or `@swagger`) with the following configuration: | ||
|
||
### Build | ||
```javascript | ||
const swaggerJsdoc = require('swagger-jsdoc'); | ||
|
||
``` | ||
$ yarn build | ||
const options = { | ||
definition: { | ||
openapi: '3.0.0', | ||
info: { | ||
title: 'Hello World', | ||
version: '1.0.0', | ||
}, | ||
}, | ||
apis: ['./src/routes*.js'], // files containing annotations as above | ||
}; | ||
|
||
const openapiSpecification = swaggerJsdoc(options); | ||
``` | ||
|
||
This command generates static content into the `build` directory and can be served using any static contents hosting service. | ||
The resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification. | ||
|
||
### Deployment | ||
![swagger-jsdoc example screenshot](/img/screenshot.png) | ||
|
||
Using SSH: | ||
## System requirements | ||
|
||
``` | ||
$ USE_SSH=true yarn deploy | ||
- Node.js 12.x or higher | ||
|
||
You are viewing `swagger-jsdoc` v6 which is published in CommonJS module system. | ||
|
||
## Installation | ||
|
||
```bash | ||
npm install swagger-jsdoc --save | ||
``` | ||
|
||
Not using SSH: | ||
Or | ||
|
||
```bash | ||
yarn add swagger-jsdoc | ||
``` | ||
$ GIT_USER=<Your GitHub username> yarn deploy | ||
|
||
## Supported specifications | ||
|
||
- OpenAPI 3.x | ||
- Swagger 2 | ||
- AsyncAPI 2.0 | ||
|
||
## Validation of swagger docs | ||
|
||
By default `swagger-jsdoc` tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag `failOnErrors` to `true`. This is for instance useful if you want to verify that your swagger docs validate using a unit test. | ||
|
||
```javascript | ||
const swaggerJsdoc = require('swagger-jsdoc'); | ||
|
||
const options = { | ||
failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false. | ||
definition: { | ||
openapi: '3.0.0', | ||
info: { | ||
title: 'Hello World', | ||
version: '1.0.0', | ||
}, | ||
}, | ||
apis: ['./src/routes*.js'], | ||
}; | ||
|
||
const openapiSpecification = swaggerJsdoc(options); | ||
``` | ||
|
||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. | ||
## Documentation | ||
|
||
Click on the version you are using from navigation bar for further details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,47 +1,103 @@ | ||
--- | ||
sidebar_position: 1 | ||
title: Intro | ||
--- | ||
|
||
# Tutorial Intro | ||
# swagger-jsdoc | ||
|
||
Let's discover **Docusaurus in less than 5 minutes**. | ||
This library reads your [JSDoc](https://jsdoc.app/)-annotated source code and generates an [OpenAPI (Swagger) specification](https://swagger.io/specification/). | ||
|
||
## Getting Started | ||
[![npm Downloads](https://img.shields.io/npm/dm/swagger-jsdoc.svg)](https://www.npmjs.com/package/swagger-jsdoc) | ||
![CI](https://github.com/Surnet/swagger-jsdoc/workflows/CI/badge.svg) | ||
|
||
Get started by **creating a new site**. | ||
## Getting started | ||
|
||
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. | ||
Imagine having API files like these: | ||
|
||
### What you'll need | ||
|
||
- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: | ||
- When installing Node.js, you are recommended to check all checkboxes related to dependencies. | ||
```javascript | ||
/** | ||
* @openapi | ||
* /: | ||
* get: | ||
* description: Welcome to swagger-jsdoc! | ||
* responses: | ||
* 200: | ||
* description: Returns a mysterious string. | ||
*/ | ||
app.get('/', (req, res) => { | ||
res.send('Hello World!'); | ||
}); | ||
``` | ||
|
||
## Generate a new site | ||
The library will take the contents of `@openapi` (or `@swagger`) with the following configuration: | ||
|
||
Generate a new Docusaurus site using the **classic template**. | ||
```javascript | ||
const swaggerJsdoc = require('swagger-jsdoc'); | ||
|
||
The classic template will automatically be added to your project after you run the command: | ||
const options = { | ||
definition: { | ||
openapi: '3.0.0', | ||
info: { | ||
title: 'Hello World', | ||
version: '1.0.0', | ||
}, | ||
}, | ||
apis: ['./src/routes*.js'], // files containing annotations as above | ||
}; | ||
|
||
```bash | ||
npm init docusaurus@latest my-website classic | ||
const openapiSpecification = swaggerJsdoc(options); | ||
``` | ||
|
||
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. | ||
The resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification. | ||
|
||
![swagger-jsdoc example screenshot](/img/screenshot.png) | ||
|
||
The command also installs all necessary dependencies you need to run Docusaurus. | ||
## System requirements | ||
|
||
## Start your site | ||
- Node.js 12.x or higher | ||
|
||
You are viewing `swagger-jsdoc` v6 which is published in CommonJS module system. | ||
|
||
## Installation | ||
|
||
```bash | ||
npm install swagger-jsdoc --save | ||
``` | ||
|
||
Run the development server: | ||
Or | ||
|
||
```bash | ||
cd my-website | ||
npm run start | ||
yarn add swagger-jsdoc | ||
``` | ||
|
||
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. | ||
## Supported specifications | ||
|
||
- OpenAPI 3.x | ||
- Swagger 2 | ||
- AsyncAPI 2.0 | ||
|
||
## Validation of swagger docs | ||
|
||
By default `swagger-jsdoc` tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag `failOnErrors` to `true`. This is for instance useful if you want to verify that your swagger docs validate using a unit test. | ||
|
||
```javascript | ||
const swaggerJsdoc = require('swagger-jsdoc'); | ||
|
||
const options = { | ||
failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false. | ||
definition: { | ||
openapi: '3.0.0', | ||
info: { | ||
title: 'Hello World', | ||
version: '1.0.0', | ||
}, | ||
}, | ||
apis: ['./src/routes*.js'], | ||
}; | ||
|
||
const openapiSpecification = swaggerJsdoc(options); | ||
``` | ||
|
||
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. | ||
## Documentation | ||
|
||
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. | ||
Click on the version you are using from navigation bar for further details. |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.