Merge pull request #326 from rockingrohit9639/master

Added version 6.x docs in docusaurus

docusaurus/docusaurus.config.js

@@ -32,7 +32,8 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
-          editUrl: 'https://github.com/Surnet/swagger-jsdoc',
+          editUrl:
+            'https://github.com/Surnet/swagger-jsdoc/tree/master/docusaurus',
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),

docusaurus/versioned_docs/version-6.x/Contributing/fundamental-concepts.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 5
+---
+
+# Fundamental concepts
+
+Please pay attention to the following shared information as it's based on recurring questions from the issue queue. Reading the following paragraphs carefully will save your time for the fun part: creating your API.
+
+## Definition and `apis`
+
+There are two fundamental concepts in `swagger-jsdoc` - definition object and input APIs.
+
+The definition object maps to [OpenAPI object](https://swagger.io/specification/#oasObject) and the input APIs are split source code parts which form the end specification.
+
+Parts of the specification can be placed in annotated JSDoc comments in non-compiled logical files. These specification parts stand close to their implementation.
+
+Other parts of the specification can be directly written in YAML files. These are usually parts containing static definitions which are referenced from jsDoc comments parameters, components, anchors, etc. which are not so relevant to the API implementation.
+
+Given the following definition `swaggerDefinition.cjs`:
+
+```javascript
+module.exports = {
+  info: {
+    title: 'Hello World',
+    version: '1.0.0',
+    description: 'A sample API',
+  },
+};
+```
+
+The end `swaggerSpecification` will be a result of following:
+
+```javascript
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerDefinition = require('./swaggerDefinition');
+
+const options = {
+  swaggerDefinition,
+  apis: ['./src/routes*.js'],
+};
+
+const swaggerSpecification = swaggerJsdoc(options);
+```
+
+## File selection patterns
+
+`swagger-jsdoc` uses [node glob](https://github.com/isaacs/node-glob) for discovering your input files. You can use patterns such as `*.js` to select all javascript files or `**/*.js` to select all javascript files in sub-folders recursively.
+
+Paths are relative to the current working directory.
+
+[Tests](https://github.com/Surnet/swagger-jsdoc/tree/v6/test)

docusaurus/versioned_docs/version-6.x/Contributing/project-goals.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 4
+title: Project Goals
+---
+
+# Project Goals
+
+**swagger-jsdoc** enables you to integrate [Swagger](http://swagger.io) using [`JSDoc`](https://jsdoc.app/) comments in your code. Just add `@swagger` (or `@openapi`) on top of an API-related annotation and and describe the given API part in YAML syntax. It's possible to pass YAML files directly outside the annotated source code.
+
+`swagger-jsdoc` will parse the above-mentioned parts of your desired specification and will output a single file. You can use it to integrate any server and client technology as long as both sides comply with the specification.
+
+Thus, the `swagger-jsdoc` library helps you document existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.
+
+If you prefer to write the OpenAPI specification first and separately, you might check other projects facilitating this, such as
+
+- [swagger-editor](http://swagger.io/swagger-editor/)
+- [swagger-node](https://github.com/swagger-api/swagger-node)
+
+## What swagger-jsdoc is NOT (doing)
+
+The library does not add logic (implementation) to your specification. It is based on code annotations or static YAML files, but not the logic itself. If you use [Swagger UI](https://swagger.io/tools/swagger-ui/) or a similar tools to test your API and you receive errors, unexpected results and mystical data, it's not because of swagger-jsdoc library. It works only with what you put around your logic, not the contents of the logic.

docusaurus/versioned_docs/version-6.x/Contributing/reporting-issues.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 7
+---
+
+# Reporting issues
+
+Before starting a new issue, please [check whether there is an existing one](https://github.com/Surnet/swagger-jsdoc/issues). It is quite possible that the topic you would like to bring up has been discussed already in the past.
+
+In case of an issue which hasn't been considered yet, please include as much information as possible. This will help maintainers and other users relate to your problem and possibly solve it.
+
+Guidelines:
+
+- Describe what you were doing when the issue appeared.
+- Add a set of steps to reproduce your issue.
+- Include screenshots.
+- Give examples on expected vs actual behavior.
+- Share your failed attempts: what you have tried and what you have considered.
+
+# Contributing
+
+The project exists thanks to the [many contributors](https://github.com/Surnet/swagger-jsdoc/graphs/contributors) who shared their use cases, questions, comments and suggestions for improvements.
+
+Here's how to jump in and contribute yourself:
+
+- Fork the project and clone it locally.
+- Create a branch for each separate topic. [Semantic commit messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716) will be highly appreciated.
+- Comment your code as if you are going to maintain it in the future.
+- Use the rich set of unit tests as an example and add more for the new use cases. This will not only enable you to programatically reproduce your fix faster than setting up an application, but it will also make you super cool! :)
+- Push to your changes to the origin of your repository and create a new pull request towards the upstream master. (this repository)

docusaurus/versioned_docs/version-6.x/Contributing/typescript.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 6
+---
+
+# Typescript
+
+## Types
+
+Please see [`@types/swagger-jsdoc`](https://www.npmjs.com/package/@types/swagger-jsdoc). The package has been created and maintained by one of the original creators of `swagger-jsdoc` [drGrove](https://github.com/drGrove).
+
+## The library
+
+It's currently written in Vanilla JavaScript compatible with Node.js 12 or higher. There are no compilation, transpilation or bundling steps. JSDoc comments and annotations have been maintained and published for intelligent editors.
+
+No types definitions are managed or published from this repository.
+
+## Re-using interfaces from source code
+
+`swagger-jsdoc` is only taking into account JSDoc comments and pure YAML files. The library does not work with source code at all: no reading, no parsing, no modifications.
+
+For scenarios in which you want the source code to be taken into account in your specification, use an alternative such as [`tsoa`](https://github.com/lukeautry/tsoa).

docusaurus/versioned_docs/version-6.x/Quick Start/cli.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 3
+title: CLI
+---
+
+# Command line interface
+
+The CLI is a thin wrapper around the library Node API. It's available with the same name of the package when installed globally:
+
+```bash
+swagger-jsdoc
+```
+
+Or through the standard ways provided by your package manager:
+
+```bash
+yarn swagger-jsdoc
+```
+
+## Usage
+
+Print the help menu:
+
+```bash
+swagger-jsdoc -h
+```
+
+### Definition file
+
+Set with `--definition` (or `-d`) flag:
+
+```bash
+swagger-jsdoc -d swaggerDefinition.js
+```
+
+Acceptable file extensions: `.cjs`, `.json`, `.yml`, `.yaml`.
+
+### Input files
+
+Set through arguments.
+
+One by one:
+
+```bash
+swagger-jsdoc -d swaggerDefinition.cjs route1.js route2.js component1.yaml component2.yaml
+```
+
+Multiple with a pattern:
+
+```bash
+swagger-jsdoc -d swaggerDefinition.cjs route*.js component*.yaml
+```
+
+[Glob patterns](https://github.com/isaacs/node-glob) are acceptable to match multiple files with same extension `*.js`, `*.php`, etc. or patterns selecting files in nested folders as `**/*.js`, `**/*.php`, etc.
+
+Paths are relative to the current working directory.
+
+### Output file (optional)
+
+The output is `swagger.json` by default, but can be changed:
+
+```bash
+swagger-jsdoc -d swaggerDefinition.cjs route1.js -o my_spec.json
+```
+
+When output file extension is `.yaml` or `.yml`, the specification will be parsed and saved in YAML format.

docusaurus/versioned_docs/version-6.x/Quick Start/first-steps.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 2
+title: First Steps
+---
+
+# First Steps
+
+## Specification version
+
+`swagger-jsdoc` was created in 2015. The OpenAPI as a concept did not exist, and thus the naming of the package itself.
+
+The default target specification is 2.0. This provides backwards compatibility for many APIs written in the last couple of years.
+
+In order to create a specification compatibile with 3.0 or higher, i.e. the so called OpenAPI, set this information in the `swaggerDefinition`:
+
+```diff
+const swaggerJsdoc = require('swagger-jsdoc');
+
+const options = {
+  swaggerDefinition: {
++   openapi: '3.0.0',
+    info: {
+      title: 'Hello World',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./src/routes*.js'],
+};
+
+const swaggerSpecification = swaggerJsdoc(options);
+```
+
+## Annotating source code
+
+Place `@swagger` or `@openapi` on top of YAML-formatted specification parts:
+
+```javascript
+/**
+ * @swagger
+ *
+ * /login:
+ *   post:
+ *     produces:
+ *       - application/json
+ *     parameters:
+ *       - name: username
+ *         in: formData
+ *         required: true
+ *         type: string
+ *       - name: password
+ *         in: formData
+ *         required: true
+ *         type: string
+ */
+app.post('/login', (req, res) => {
+  // Your implementation comes here ...
+});
+```
+
+## Using YAML
+
+It's possible to source parts of your specification through YAML files.
+
+Imagine having a file `x-amazon-apigateway-integrations.yaml` with the following contents:
+
+```yaml
+x-amazon-apigateway-integrations:
+  default-integration: &default-integration
+    type: object
+    x-amazon-apigateway-integration:
+      httpMethod: POST
+      passthroughBehavior: when_no_match
+      type: aws_proxy
+      uri: 'arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789:function:helloworldlambda/invocations'
+```
+
+The following is an acceptable reference to information from `x-amazon-apigateway-integrations.yaml` when it's defined within the `apis` input array.
+
+```javascript
+  /**
+   * @swagger
+   * /aws:
+   *   get:
+   *     description: contains a reference outside this file
+   *     x-amazon-apigateway-integration: *default-integration
+   */
+  app.get('/aws', (req, res) => {
+    // Your implementation comes here ...
+  });
+};
+```
+
+## Further resources
+
+Additional materials to inspire you:
+
+- [Document your Javascript code with JSDoc](https://dev.to/paulasantamaria/document-your-javascript-code-with-jsdoc-2fbf) - 20/08/2019
+- [Swagger: Time to document that Express API you built!](https://levelup.gitconnected.com/swagger-time-to-document-that-express-api-you-built-9b8faaeae563) - 25/05/2019
+  [Express API with autogenerated OpenAPI doc through Swagger](https://www.acuriousanimal.com/blog/2018/10/20/express-swagger-doc) - 20/10/2018
+- [Express에 Swagger 붙이기](https://gongzza.github.io/javascript/nodejs/swagger-node-express/) - 18/07/2018
+- [Swaggerize your API Documentation](http://imaginativethinking.ca/swaggerize-your-api-documentation/) - 01/06/2018
+- [Swagger and NodeJS](https://mherman.org/blog/swagger-and-nodejs/) 20/11/2017
+- [Agile documentation for your API-driven project](https://kalinchernev.github.io/agile-documentation-api-driven-project) - 21/01/2017
+
+Suggestions for extending this helpful list are welcome! [Submit your article](https://github.com/Surnet/swagger-jsdoc/issues/new)
+
+## Examples
+
+Here's a list of example public open-source usages of the package:
+
+- [godaddy/gasket](https://github.com/godaddy/gasket)
+- [godaddy/warehouse.ai-status-api](https://github.com/godaddy/warehouse.ai-status-api)
+- [hana-developer-cli-tool-example](https://github.com/SAP-samples/hana-developer-cli-tool-example)
+- [studiohyperdrive/api-docs](https://github.com/studiohyperdrive/api-docs)
+- [More Examples](https://github.com/Surnet/swagger-jsdoc/tree/v6/examples)
+
+## Related projects
+
+- [godaddy/swagger-jsdoc-deref](https://github.com/godaddy/swagger-jsdoc-deref)
+- [slanatech/swagger-stats](https://github.com/slanatech/swagger-stats)
+- [weseek/growi](https://github.com/weseek/growi)
+- [linagora/openpaas-esn](https://github.com/linagora/openpaas-esn)
+- [Tiemma/sonic-express](https://github.com/Tiemma/sonic-express)
+- [kevoj/nodetomic-api-swagger](https://github.com/kevoj/nodetomic-api-swagger)
+- [node-express-mongoose-boilerplate](https://github.com/hagopj13/node-express-mongoose-boilerplate)

docusaurus/versioned_docs/version-6.x/intro.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+title: Intro
+---
+
+# swagger-jsdoc
+
+Document your code and keep a live and reusable OpenAPI (Swagger) specification. This specification can be the core of your API-driven project: generate
+documentation, servers, clients, tests and much more based on the rich [OpenAPI ecosystem of tools](http://swagger.io/).
+
+[![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)
+
+## Goals
+
+**swagger-jsdoc** enables you to integrate [Swagger](http://swagger.io)
+using [`JSDoc`](https://jsdoc.app/) comments in your code. Just add `@swagger` (or `@openapi`) on top of your DocBlock and declare the meaning of your code in YAML complying to the OpenAPI specification. If you prefer to keep some parts of your specification aside your code in order to keep it lighter/cleaner, you can also pass these parts as separate input YAML files.
+
+`swagger-jsdoc` will parse the above-mentioned and output an OpenAPI specification. You can use it to integrate any server and client technology as long as both sides comply with the specification.
+
+Thus, the `swagger-jsdoc` project assumes that you want document your existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.
+
+If you prefer to write the OpenAPI specification first and separately, you might check other projects facilitating this, such as
+
+- [swagger-editor](http://swagger.io/swagger-editor/)
+- [swagger-node](https://github.com/swagger-api/swagger-node)
+
+### Webpack integration
+
+You can use this package with a webpack plugin to keep your swagger documentation up-to-date when building your app:
+
+- [swagger-jsdoc-webpack-plugin](https://github.com/patsimm/swagger-jsdoc-webpack-plugin) - Rebuild the swagger definition based on a predefined list of files on each webpack build.
+- [swagger-jsdoc-sync-webpack-plugin](https://github.com/gautier-lefebvre/swagger-jsdoc-sync-webpack-plugin) - Rebuild the swagger definition based on the files imported in your app on each webpack build.
+
+## Supported versions
+
+- OpenAPI 3.x
+- Swagger 2.0
+
+To make sure your end specification is valid, do read the most up-to date official [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification).

docusaurus/versioned_sidebars/version-6.x-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "tutorialSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

docusaurus/versions.json

@@ -1,3 +1,4 @@
 [
+  "6.x",
   "5.x"
 ]