Merge pull request #327 from rockingrohit9639/master

Added version 7.x documentation in docusaurus
Surnet · Aug 8, 2022 · e365124 · e365124
2 parents 832aab1 + c8ecea8
commit e365124
Show file tree

Hide file tree

Showing 33 changed files with 1,024 additions and 603 deletions.
diff --git a/docusaurus/.eslintrc.json b/docusaurus/.eslintrc.json
@@ -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
+  }
+}
diff --git a/docusaurus/README.md b/docusaurus/README.md
@@ -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.
diff --git a/docusaurus/docs/intro.md b/docusaurus/docs/intro.md
@@ -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.
diff --git a/docusaurus/docs/tutorial-basics/_category_.json b/docusaurus/docs/tutorial-basics/_category_.json
diff --git a/docusaurus/docs/tutorial-basics/congratulations.md b/docusaurus/docs/tutorial-basics/congratulations.md
diff --git a/docusaurus/docs/tutorial-basics/create-a-blog-post.md b/docusaurus/docs/tutorial-basics/create-a-blog-post.md