{"_id":"@autp-swteam/swagger-autogen","_rev":"1-f73661b73ae7ab51754012bf9b4f0e38","name":"@autp-swteam/swagger-autogen","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@autp-swteam/swagger-autogen","version":"1.0.0","description":"This module performs the automatic construction of the Swagger documentation. The module is able to identify the endpoints and automatically capture methods such as get, post, put, and so on. The module can also identify the paths, routes, middlewares, re","main":"swagger-autogen.js","scripts":{"pretest":"eslint --ignore-path .gitignore .","test":"node test/index.js | tap-spec","code-formatter":"prettier --config .prettierrc 'src/**/*.js' --write"},"private":false,"keywords":["swagger","autogen","generated","automatically","documentation","swagger-autogen","auto","automatic","generator","generate","autogenerate","autogenerator","autogenerated"],"author":{"name":"autp-swteam","email":"autp.aclac0@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/autp-swteam/swagger-autogen.git"},"devDependencies":{"eslint":"^7.26.0","prettier":"^2.3.0","tap-spec":"^5.0.0","tape":"^4.11.0","tape-promise":"^4.0.0"},"dependencies":{"acorn":"^7.4.1","deepmerge":"^4.2.2","glob":"^7.1.7","json5":"^2.2.0"},"bugs":{"url":"https://github.com/autp-swteam/swagger-autogen/issues"},"homepage":"https://github.com/autp-swteam/swagger-autogen#readme","_id":"@autp-swteam/swagger-autogen@1.0.0","_nodeVersion":"12.22.8","_npmVersion":"6.14.15","dist":{"integrity":"sha512-n+wIZx+ucP4hzU3Steh/Wnux9qzfAi3czPkWPnwJ9AWWWSyCzG9cMj+OrRS6rIDRAbK6n4tfRZdW7BoN88xIBg==","shasum":"cc22637b6e6c1fd729d6e1b8cad27c56084a208f","tarball":"https://registry.npmjs.org/@autp-swteam/swagger-autogen/-/swagger-autogen-1.0.0.tgz","fileCount":14,"unpackedSize":253885,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJh7grXCRA9TVsSAnZWagAA3AwP/iVWLNWCbd9J4kZj3he5\nECiQYZVaska7YPki6oywVywG0rsmklI9L9n2UfmMMRiS/50YTmw0UvgLl5ox\nIy8cYyyZU90TkSehka53UhePOf1kBkqhO51GSiZ6EHXDM6wJeHM3BtI7yU4w\nk+Qa6HQhZsfynNA6EjPyQnXIP95x8/rT5a1qiM31YPYNY0zwTcgOgUjRxvYV\nVceKghXrc8Bo8ibs7eeJO0ivwjXbJ4ZLgXrkAwDvh7cDcYYFWqwtmSfvqRO4\nsQoLmpp/mhCAkno4mgxogeachVbJyk4LL6m1GvnTnQHpyB5ItNO2qQ6SHpEa\nx+aMOzkgqnkBv31/yj2WJd2KhS6g6BpbfWe/d2rF2OQ8G+r6a1+gcVHFK+gb\nwtURntFvQdlfWzvean566WI+37bF5ZFPALs0F/InmhWppT2scFMqbDpk5Mj+\nqMX5q0y464dx7FWIQ3dIVKv0x2Je1aJmEY2INI72NgWnpzHgyhz3ldWbM98q\nvd9SkZTqNtzcRUTyCpVYuA9Jec3Tm7HDFGBWwPvvtT3mag2jeG2UgUw7U5nP\nXZ1HzpdNQhgQ2tkXzqRXcvtdWViWy+ABt2s3reLD3lh09QEr9KHmm/kNKo+l\nhsDz0k8Cj1AcEU0ekHWAV4VJn5QoJPOQLUOIwRK4czR+/TbNl5ZaPmt3IGnT\nwYpg\r\n=ZKSE\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCOyxRrXnF17Y/+KBKHxmfAJB5bSUNJNKLzvFrNLy0YsAIhAL9kfPx4bru/i2C8Q7lGJd/kH4XNs3bsdgm1lnZBLSVR"}]},"_npmUser":{"name":"autp-swteam","email":"autp.aclac0@gmail.com"},"directories":{},"maintainers":[{"name":"autp-swteam","email":"autp.aclac0@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/swagger-autogen_1.0.0_1642990294915_0.18110813321103958"},"_hasShrinkwrap":false}},"time":{"created":"2022-01-24T02:11:34.846Z","1.0.0":"2022-01-24T02:11:35.160Z","modified":"2022-04-04T16:41:20.886Z"},"maintainers":[{"name":"autp-swteam","email":"autp.aclac0@gmail.com"}],"description":"This module performs the automatic construction of the Swagger documentation. The module is able to identify the endpoints and automatically capture methods such as get, post, put, and so on. The module can also identify the paths, routes, middlewares, re","homepage":"https://github.com/autp-swteam/swagger-autogen#readme","keywords":["swagger","autogen","generated","automatically","documentation","swagger-autogen","auto","automatic","generator","generate","autogenerate","autogenerator","autogenerated"],"repository":{"type":"git","url":"git+https://github.com/autp-swteam/swagger-autogen.git"},"author":{"name":"autp-swteam","email":"autp.aclac0@gmail.com"},"bugs":{"url":"https://github.com/autp-swteam/swagger-autogen/issues"},"license":"MIT","readme":"# swagger-autogen\n\nThis module performs the automatic construction of the Swagger documentation. The module can identify the endpoints and automatically capture methods such as to get, post, put, and so on. The module can also identify the paths, routes, middlewares, response status code, parameters in the path, query and body. It is possible to add information such as endpoint description, parameter description, definitions, security, among others. It is also possible to ignore or disable the automatic capture of an endpoint (in the latter case, having to manually add each information). The module generates the *.json* file with the documentation in the swagger format.\n\n[![NPM Version](http://img.shields.io/npm/v/swagger-autogen.svg?style=flat)](https://www.npmjs.com/package/swagger-autogen)\n[![NPM Downloads](https://img.shields.io/npm/dm/swagger-autogen.svg?style=flat)](https://npmcharts.com/compare/swagger-autogen?minimal=true)\n[![Known Vulnerabilities](https://snyk.io/test/npm/swagger-autogen/badge.svg)](https://snyk.io/test/npm/swagger-autogen)\n\n## Contents\n\n- [Installation](#installation)\n- [Update](#update)\n- [Usage](#usage)\n  - [Usage (Basic)](#usage-basic)\n  - [Usage (With Optionals)](#usage-with-optionals)\n- [Building documentation without starting the project](#building-documentation-without-starting-the-project)\n- [Building documentation at project startup](#building-documentation-at-project-startup)\n- [Options](#options)\n- [Endpoints](#endpoints)\n  - [Automatic capture](#automatic-capture)\n  - [Tags](#tags)\n  - [Summary](#summary)\n  - [Description](#description)\n  - [Operation ID](#operation-id)\n  - [Consumes and Produces](#consumes-and-produces)\n  - [Parameters](#parameters)\n  - [Request Body](#request-body)\n  - [Responses](#responses)\n  - [Schema and Definitions](#schema-and-definitions)\n    - [Examples of Definitions](#examples-of-definitions)\n  - [Endpoint as deprecated](#endpoint-as-deprecated)\n  - [Ignoring endpoint](#ignoring-endpoint)\n  - [Manual capture](#manual-capture)\n  - [Forced endpoint creation](#forced-endpoint-creation)\n- [Security](#security)\n  - [API Keys (Token) example](#api-keys-token-example)\n  - [OAuth2 example](#oauth2-example)\n- [Response Language](#response-language)\n- [Examples](#examples)\n- [Compatibility](#compatibility)\n- [Tutorials](#tutorials)\n- [Changelog](#changelog)\n- [Help us!](#help-us)\n- [License](#license)\n\n## Installation\n\nThis is a [Node.js](https://nodejs.org/en/) module available through the [npm](https://www.npmjs.com/).\n\n```bash\n$ npm install --save-dev swagger-autogen\n```\n\nIf you're using CommonJS:\n\n```js\nconst swaggerAutogen = require('swagger-autogen')();\n```\n\nOr if you're using ES modules:\n\n```js\nimport swaggerAutogen from 'swagger-autogen';\n```\n\n## Update\n\nIf you already have the module installed and want to update to the latest version, use the command:\n\n```bash\n$ npm install --save-dev swagger-autogen@2.11.2\n```\n\n## Usage\n\n[Example using Router](https://github.com/davibaltar/example-swagger-autogen-with-router)\n\n[Example without Router](https://github.com/davibaltar/example-swagger-autogen)\n\n[See Tutorial in English](https://medium.com/@davibaltarx/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284)\n\n[See Tutorial em Português Brasil](https://medium.com/@davibaltarx/documenta%C3%A7%C3%A3o-autom%C3%A1tica-de-apis-em-node-js-eb03041c643b)\n\nThe two sections below will show the most basic and most complete use of this module.\n\nFunction signature:\n\n```js\nconst swaggerAutogen: (outputFile: <string>, endpointsFiles: <Array of string>, data: <object>) => Promise <any>\n```\n\n**outputFile:** (Required*). Output file. It will be the file generated by the module containing the documentation in the format identified by Swagger.\n\n**endpointsFiles:** (Required*). Files containing the endpoints. These are the files that contain methods such as get, post, put, and so on, for example: `app.get('/path', ...)` or `route.post('/path', ...)`.\n\n**doc:** (Not Required). An object containing the details of the documentation. If not informed, or if any parameter of the object is omitted, the default values ​​will be used. (See: [Usage (With optionals)](#usage-with-optionals) section)\n\n### Usage (Basic)\n\nThe code below must be inserted in a separate file (e.g *swagger.js*):\n\n**File: swagger.js**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')();\n\nconst doc = {\n  info: {\n    title: 'My API',\n    description: 'Description',\n  },\n  host: 'localhost:3000',\n  schemes: ['http'],\n};\n\nconst outputFile = './path/swagger-output.json';\nconst endpointsFiles = ['./path/endpointsUser.js', './path/endpointsBook.js'];\n\n/* NOTE: if you use the express Router, you must pass in the \n   'endpointsFiles' only the root file where the route starts,\n   such as index.js, app.js, routes.js, ... */\n\nswaggerAutogen(outputFile, endpointsFiles, doc);\n```\n\n### Usage (With optionals)\n\nThe code below must be inserted in a separate file, for example:\n\n**File: swagger.js**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')();\n\nconst doc = {\n  info: {\n    version: '',      // by default: '1.0.0'\n    title: '',        // by default: 'REST API'\n    description: '',  // by default: ''\n  },\n  host: '',      // by default: 'localhost:3000'\n  basePath: '',  // by default: '/'\n  schemes: [],   // by default: ['http']\n  consumes: [],  // by default: ['application/json']\n  produces: [],  // by default: ['application/json']\n  tags: [        // by default: empty Array\n    {\n      name: '',         // Tag name\n      description: '',  // Tag description\n    },\n    // { ... }\n  ],\n  securityDefinitions: {},  // by default: empty object\n  definitions: {},          // by default: empty object\n};\n\nconst outputFile = './path/swagger-output.json';\nconst endpointsFiles = ['./path/endpointsUser.js', './path/endpointsBook.js'];\n\n/* NOTE: if you use the express Router, you must pass in the \n   'endpointsFiles' only the root file where the route starts,\n   such as: index.js, app.js, routes.js, ... */\n\nswaggerAutogen(outputFile, endpointsFiles, doc);\n```\n\n**NOTE:** If you're using ES modules, use:\n```js\nswaggerAutogen()(outputFile, endpointsFiles, doc);\n```\n\n**NOTE:** To omit any of the attributes in the *.json* file, just assign the value **null** to the specified attribute in the **doc**.\n\n## Building documentation without starting the project\n\nTo build the documentation without starting your project, add the following script to your project's _package.json_ file:\n\n**File: package.json**\n\n```js\n    // { ... },\n    \"scripts\": {\n        // ... ,\n        \"swagger-autogen\": \"node ./swagger.js\"\n    }\n```\n\nWhere `./swagger.js` is the file containing the `swaggerAutogen(...)` function call (see section [Usage](#usage). After that, at the root of your project, run the following command:\n\n```bash\n$ npm run swagger-autogen\n```\n\n## Building documentation at project startup\n\nTo build the documentation before the project starts and immediately start it, rewrite the `swaggerAutogen(...)` function as follows:\n\nIf you're using CommonJS, use:\n\n```js\n// ...\nswaggerAutogen(outputFile, endpointsFiles, doc).then(() => {\n  require('./index.js'); // Your project's root file\n});\n```\n\nIn case, you're using ES modules in your project, rewrite the `swaggerAutogen(...)` function as follows:\n\n```js\n// ...\nswaggerAutogen()(outputFile, endpointsFiles, doc).then(async () => {\n  await import('./index.js'); // Your project's root file\n});\n```\n\nWhere *index.js* is your project's root file. Change the *start* script in your project's *package.json* to point to the file containing the `swaggerAutogen(...)` function. If you use Visual Studio Code, change the reference in your *launch.json* in the same way. Now, just run your project as usual. With that, the documentation will be generated, and soon after the project will start, automatically updating the documentation as soon as the project start.\n\nSee: [Complete example](https://github.com/davibaltar/example-swagger-autogen)\n\n## Options\n\nIt is possible to change some options of the module by passing an object as a parameter. This object is **optional**.\n\n```js\nconst options = {\n    openapi: <string>,          // By default is null\n    language: <string>,         // By default is 'en-US'\n    disableLogs: <boolean>,     // By default is false\n    disableWarnings: <boolean>  // By default is false\n}\n```\n\nIf you're using CommonJS, use:\n\n```js\nconst swaggerAutogen = require('swagger-autogen')(options)\n```\n\nIn case, you're using ES modules in your project, rewrite the `swaggerAutogen(...)` function as follows:\n\n```js\nimport swaggerAutogen from 'swagger-autogen';\n// ...\nswaggerAutogen(options)(outputFile, endpointsFiles, doc).then(async () => {\n  await import('./index.js'); // Your project's root file\n});\n```\n\n**OpenAPI:** To enable OpenAPI v3, assign a version, such as \"3.0.0\" to the *openapi* parameter. In the future, OpenAPI v3 will be the default.\n\nTo see the available languages, go to the section [Response Language](#response-language)\n\n## Endpoints\n\nThe way to configure the module is done within comments, and can be in the format `// ...` or `/* ... */`. The used pattern will be `#swagger.something` tag. Each comment can contain one or more `#swagger.something` tags. **NOTE:** ALL COMMENTS CONTAINING `#swagger.something` MUST BE WITHIN THE FUNCTIONS.\n\n### Automatic capture\n\nIn this case, it is not necessary to do anything. Considering, for example, if the pattern of your API is as follows:\n\n```js\n    ...\n    app.post('/users', (req, res) => {\n        ...\n        users.addUser(req.query.obj)\n        ...\n        if(...)\n            return res.status(201).send(data)\n        ...\n        return res.status(500).send(false)\n    })\n    ...\n```\n\nThe recognition of the method, path, parameters and status of the response will be automatic.\n\nSee an [example here!](#examples)\n\n### Tags\n\nTo inform which tags the endpoints belong to, use the `#swagger.tags` tag, for example:\n\n```js\n    ...\n    app.get('/users', (req, res) => {\n        ...\n        // #swagger.tags = ['Users']\n        ...\n    })\n```\n\n### Summary\n\nThis is the summary of the Endpoint. To add it, use the `#swagger.summary` tag, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.summary = 'Your summary here'\n        ...\n    })\n```\n\n### Description\n\nThis is the description of the Endpoint. To add it, use the `#swagger.description` tag, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.description = 'Endpoint used to obtain a user.'\n        ...\n    })\n```\n\n### Operation ID\n\nThis is the operationId of the Endpoint. To add it, use the `#swagger.operationId` tag, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.operationId = 'Your_operationId_here'\n        ...\n    })\n```\n\n### Consumes and Produces\n\nUse the `#swagger.produces = ['contentType']` or `#swagger.consumes = ['contentType']` tag to add a new produce or a new consume, respectively. In the **Example (Consumes)** below, the two endpoints will have the same result in the documentation.\n\n**Example (Consumes):**\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // Recognizes the 'consumes' automatically\n        res.setHeader('Content-Type', 'application/xml')\n        ...\n    })\n```\n\nOR\n\n```js\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.consumes = ['application/xml']\n        ...\n    })\n```\n\n**Example (Produces):**\n\n```js\n    ...\n    app.get('/v2/users/:id', (req, res) => {\n        ...\n        // #swagger.produces = ['application/json']\n        ...\n    })\n```\n\n### Parameters\n\nIt is possible to create or complement automatically detected parameters. Use the `#swagger.parameters['parameterName']` tag to create a new parameter or to complete an existing parameter (automatically detected).\n\nAll optional parameters:\n\n```js\n/* #swagger.parameters['parameterName'] = {\n        in: <string>,\n        description: <string>,\n        required: <boolean>,\n        type: <string>,\n        format: <string>,\n        schema: <object> or <Array>\n} */\n```\n\n**in:** 'path', 'query', 'body', 'formData', etc.      // by default is 'query'  \n**description:** The parameter description  \n**required:** true or false  \n**type:** 'string', 'integer', 'object', 'array', etc. // by default is 'string' when 'schema' is missing  \n**format:** 'int64', etc.  \n**schema:** See section [Schema and Definitions](#schema-and-definitions)\n\nSome examples:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        //  #swagger.parameters['id'] = { description: 'User ID' }\n        ...\n    })\n\n    app.post('/books', (req, res) => {\n        ...\n        /*  #swagger.parameters['obj'] = {\n                in: 'body',\n                type: 'object',\n                description: 'Book data'\n        } */\n        users.addUser(req.body)\n        ...\n    })\n\n    app.post('/users', (req, res) => {\n        ...\n        /*  #swagger.parameters['obj'] = {\n                in: 'body',\n                description: 'Add a user',\n                schema: { $ref: '#/definitions/AddUser' }\n        } */\n        ...\n    })\n\n    app.get('/users', async (req, res) => {\n        /*  #swagger.parameters['item'] = {\n                in: 'query',\n                description: 'Any item...'\n        } */\n        let test = req.query.item\n    });\n\n    // (Swagger 2.0) Upload single file using Multer\n    app.post(\"/upload\", uploader.single(\"singleFile\"), (req, res) => {\n        /*\n          #swagger.consumes = ['multipart/form-data']  \n          #swagger.parameters['singleFile'] = {\n              in: 'formData',\n              type: 'file',\n              required: 'true',\n              description: 'Any description...',\n        } */\n\n        const file = req.file;\n    });\n\n    // (Swagger 2.0) Upload multiple files using Multer\n    app.post(\"/uploads\", uploader.array(\"multFiles\", 2), (req, res) => {\n        /*\n          #swagger.consumes = ['multipart/form-data']  \n          #swagger.parameters['multFiles'] = {\n              in: 'formData',\n              type: 'array',\n              required: true,\n              description: 'Any description...',\n              collectionFormat: 'multi',\n              items: { type: 'file' }\n          } */\n\n        const files = req.files;\n    });\n\n```\n\nClick here to see: [\"#/definitions/AddUser\"](#schema-and-definitions)\n\n#### Body\n\nThe **body** is automatically recognized, for example:\n\n```js\n    app.post('/users', (req, res) => {\n\n        const myItem1 = req.body.item1\n\n        const { item2, item3 } = req.body\n\n        ...\n    })\n```\n\n**NOTE:** But, if there is any `#swagger.parameters[...] = { in: 'body', ... }` with **schema** declared, the recognition of **body** will be ignored, for example:\n\n```js\n    app.post('/users', (req, res) => {\n        /*  #swagger.parameters['parameter_name'] = {\n                in: 'body',\n                description: 'Any description...',\n                schema: {\n                    $name: 'Jhon Doe',\n                    $age: 29,\n                    about: ''\n                }\n        } */\n\n        const myItem1 = req.body.item1  // Will be ignored\n\n        const { item2, item3 } = req.body  // Will be ignored\n\n        ...\n    })\n```\n\nHowever, if you wish to add more information to the automatically recognized **body**, declared the `#swagger.parameters` adding **in: 'body'**, BUT without the **schema**, such as:\n\n```js\n    app.post('/users', (req, res) => {\n        /*  #swagger.parameters['any_name'] = {\n               in: 'body',\n               description: 'Any description...'\n        } */\n\n        const myItem1 = req.body.item1\n\n        const { item2, item3 } = req.body\n\n        ...\n    })\n```\n\nAutomatically the **body** will be recognized and the parameters 'any_name' and 'description' will be assigned to the **body**.\n\n### Responses\n\nIt is possible to create or complement automatically detected responses. Use the `#swagger.reponses[statusCode]` tag to create a new answer or to complete an existing answer (automatically detected).\n\nAll optional parameters:\n\n```js\n/* #swagger.responses[<number>] = {\n        description: <string>,\n        schema: <object> or <Array>\n} */\n```\n\n**description:** The parameter description.  \n**schema:** See section [Schema and Definitions](#schema-and-definitions)\n\nFor example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n\n        if(...)\n            return res.status(404)\n\n        try {\n\n            /* #swagger.responses[200] = {\n                    description: 'User successfully obtained.',\n                    schema: { $ref: '#/definitions/User' }\n            } */\n            return res.status(200).send(data)\n\n        } catch (err) {\n            // #swagger.responses[500] = { description: 'Problem with the server.' }\n            return res.status(500)\n        }\n\n    })\n```\n\n**NOTE:** For more information about **schema** and **definitions**, see the section: [Schema and Definitions](#schema-and-definitions)\n\n**NOTE:** As the 404 status description was not entered, \"Not Found\" will automatically be added. It is possible to change the language of the automatic response, see the [Response Language](#response-language) section.\n\n### Request Body\n\nUse the `#swagger.requestBody` tag to impletent [Request Body](https://swagger.io/docs/specification/describing-request-body/).\n\nTo use this feature, you need to enable the OpenAPI v3 in the options:\nIf you're using CommonJS, use:\n\n```js\nconst swaggerAutogen = require('swagger-autogen')({openapi: '3.0.0'})\n```\n\nIn case, you're using ES modules in your project, rewrite the `swaggerAutogen(...)` function as follows:\n\n```js\nimport swaggerAutogen from 'swagger-autogen';\n// ...\nswaggerAutogen({openapi: '3.0.0'})(outputFile, endpointsFiles, doc).then(async () => {\n  await import('./index.js'); // Your project's root file\n});\n```\n\n**Endpoint example:** \n```js\napp.post('/path', (req, res, next) => {\n    /*\t#swagger.requestBody = {\n            required: true,\n            content: {\n                \"application/json\": {\n                    schema: {\n                        $ref: \"#/definitions/User\"\n                    }  \n                },\n                \"application/xml\": {\n                    schema: {\n                        $ref: \"#/definitions/User\"\n                    }  \n                }\n            }\n    } */\n})\n```\n\n### Schema and Definitions\n\nUnlike how Swagger writes, the answers in this module are added more simply, that is, in the way you want to see the result. These responses can be added to the *definitions* parameter of the *doc* object seen in the [Usage](#usage) section, or directly to the response via the *schema* parameter.\n\n**About Examples and Types in the schema:** The example comes right in front of the parameter declaration, and the type is abstracted according to the *typeof* of the example. In the code below, the parameter \"name\" will have as an example \"Jhon Doe\" and type string, while \"age\" will have as an example 29 and type number.\n\n**NOTE:** To configure a parameter as **required**, just add the symbol **$** before the parameter, for example: `$name = \"Jhon Doe\"`.\n\nFor example:\n\n```js\nconst doc = {\n  // { ... },\n  definitions: {\n    Parents: {\n      father: 'Simon Doe',\n      mother: 'Marie Doe'\n    },\n    User: {\n      name: 'Jhon Doe',\n      age: 29,\n      parents: {\n        $ref: '#/definitions/Parents'\n      },\n      diplomas: [\n        {\n          school: 'XYZ University',\n          year: 2020,\n          completed: true,\n          internship: {\n            hours: 290,\n            location: 'XYZ Company'\n          }\n        }\n      ]\n    },\n    AddUser: {\n      $name: 'Jhon Doe',\n      $age: 29,\n      about: ''\n    },\n    // { ... }\n  }\n};\n```\n\n`Endpoint file:`\n\n```js\n    app.post('/users', (req, res) => {\n        ...\n        /*    #swagger.parameters['obj'] = {\n                in: 'body',\n                description: 'Adding new user.',\n                schema: { $ref: '#/definitions/AddUser' }\n        } */\n        ...\n    })\n```\n\nor inserting directly, without using definitions:\n\n```js\n    app.post('/users', (req, res) => {\n        ...\n        /*    #swagger.parameters['obj'] = {\n                in: 'body',\n                description: 'Adding new user.',\n                schema: {\n                    $name: 'Jhon Doe',\n                    $age: 29,\n                    about: ''\n                }\n        } */\n        ...\n    })\n```\n\n#### Examples of Definitions\n\nThe following are some examples of definitions:\n\n**Definitions:**\n\n```js\nconst doc = {\n  // { ... },\n  definitions: {\n    myBoolean: true,\n    myNumber: 123,\n    myString: 'my example',\n    myObject: {\n      field: 'my example'\n    },\n    myArrayOfBooleans: [true],\n    myArrayOfNumbers: [123],\n    myArrayOfStrings: ['my example'],\n    myArrayOfObjects: [\n      {\n        field: 'my example'\n      }\n    ],\n    myReferencedObjectArray: [{ $ref: '#/definitions/myObject' }]\n  }\n};\n```\n\n**Endpoint:**\n\n```js\napp.get('/responses', (req, res) => {\n  /* #swagger.responses[001] = {\n      description: 'myBoolean',\n      schema: { $ref: '#/definitions/myBoolean' }\n  } */\n\n  /* #swagger.responses[002] = {\n      description: 'myNumber',\n      schema: { $ref: '#/definitions/myNumber' }\n  } */\n\n  /* #swagger.responses[003] = {\n      description: 'myString',\n      schema: { $ref: '#/definitions/myString' }\n  } */\n\n  /* #swagger.responses[004] = {\n      description: 'myObject',\n      schema: { $ref: '#/definitions/myObject' }\n  } */\n\n  /* #swagger.responses[005] = {\n      description: 'myArrayOfBooleans',\n      schema: { $ref: '#/definitions/myArrayOfBooleans' }\n  } */\n\n  /* #swagger.responses[006] = {\n      description: 'myArrayOfNumbers',\n      schema: { $ref: '#/definitions/myArrayOfNumbers' }\n  } */\n\n  /* #swagger.responses[007] = {\n      description: 'myArrayOfStrings',\n      schema: { $ref: '#/definitions/myArrayOfStrings' }\n  } */\n\n  /* #swagger.responses[008] = {\n      description: 'myArrayOfObjects',\n      schema: { $ref: '#/definitions/myArrayOfObjects' }\n  } */\n\n  /* #swagger.responses[009] = {\n      description: 'myReferencedObjectArray',\n      schema: { $ref: '#/definitions/myReferencedObjectArray' }\n  } */\n});\n```\n\nThe result will be:\n\n![](https://raw.githubusercontent.com/davibaltar/public-store/master/example-of-definitions.png)\n\n### Endpoint as deprecated\n\nUse the `#swagger.deprecated = true` tag to inform that a given endpoint is depreciated, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.deprecated = true\n        ...\n    })\n```\n\n### Ignoring endpoint\n\nUse the `#swagger.ignore = true` tag to ignore a given endpoint. Thus, it will not appear in the documentation, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        // #swagger.ignore = true\n        ...\n    })\n```\n\n### Manual capture\n\nUse the `#swagger.auto = false` tag to disable automatic recognition. With that, all parameters of the endpoint must be informed manually, for example:\n\n```js\n    ...\n    app.put('/users/:id', (req, res) => {\n    ...\n        /*  #swagger.auto = false\n\n            #swagger.path = '/users/{id}'\n            #swagger.method = 'put'\n            #swagger.produces = ['application/json']\n            #swagger.consumes = ['application/json']\n\n            #swagger.parameters['id'] = {\n                in: 'path',\n                description: 'User ID.',\n                required: true,\n                type: 'integer'\n            }\n\n            #swagger.parameters['obj'] = {\n                in: 'body',\n                description: 'User data.',\n                required: true,\n                type: 'string'\n            }\n        */\n        ...\n        if(...) {\n            // #swagger.responses[201] = { description: 'User registered successfully.' }\n            return res.status(201).send(data)\n        }\n        ...\n        // #swagger.responses[500] = { description: 'Server failure.'}\n        return res.status(500).send(false)\n    })\n```\n\n### Forced Endpoint Creation\n\nIf you want to forcibly create an endpoint, use the `#swagger.start` and` #swagger.end` tags, for example:\n\n```js\nfunction myFunction(param) {\n    // #swagger.start\n    ...\n    /*\n        #swagger.path = '/forcedEndpoint/{id}'\n        #swagger.method = 'put'\n        #swagger.description = 'Forced endpoint.'\n        #swagger.produces = ['application/json']\n    */\n    ...\n    /*  #swagger.parameters['id'] = {\n            in: 'path',\n            type: 'integer',\n            description: 'User ID.' } */\n    const dataId = users.getUser(req.params.id)\n    ...\n    /*  #swagger.parameters['obj'] = {\n            in: 'query',\n            description: 'User data.',\n            schema: { $ref: '#/definitions/AddUser' }\n    } */\n    const dataObj = users.getUser(req.query.obj)\n    ...\n    if (...)\n        return res.status(200).send(true)    // #swagger.responses[200]\n    ...\n    return res.status(404).send(false)       // #swagger.responses[404]\n    ...\n    // #swagger.end\n}\n```\n\n## Security\n\nIt is possible to add security to endpoints. The following are some examples, but a complete approach can be seen on the website [swagger.io](#https://swagger.io/docs/specification/authentication)\n\n### API Keys (Token) example\n\nThe security example below was taken from the original Swagger documentation.\n\n```js\nconst doc = {\n  // { ... },\n  securityDefinitions: {\n    apiKeyAuth: {\n      type: 'apiKey',\n      in: 'header', // can be 'header', 'query' or 'cookie'\n      name: 'X-API-KEY', // name of the header, query parameter or cookie\n      description: 'any description...'\n    },\n  },\n};\n```\n\nTo see more about the properties of the **doc**, see the [Usage (With Optionals)](#usage-with-optionals) section.\n\nAt the endpoint, add the `#swagger.security` tag, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        /* #swagger.security = [{\n               \"apiKeyAuth\": []\n        }] */\n        ...\n    })\n```\n\n### OAuth2 example\n\nThe security example below was taken from the original Swagger documentation.\n\n```js\nconst doc = {\n  // { ... },\n  securityDefinitions: {\n    oAuthSample: {\n      type: 'oauth2',\n      authorizationUrl: 'https://petstore.swagger.io/oauth/authorize',\n      flow: 'implicit',\n      scopes: {\n        read_pets: 'read your pets',\n        write_pets: 'modify pets in your account'\n      }\n    }\n  }\n};\n```\n\nTo see more about the properties of the **doc**, see the [Usage (With Optionals)](#usage-with-optionals) section.\n\nAt the endpoint, add the `#swagger.security` tag, for example:\n\n```js\n    ...\n    app.get('/users/:id', (req, res) => {\n        ...\n        /* #swagger.security = [{\n            \"oAuthSample\": [\n                \"write_pets\",\n                \"read_pets\"\n            ]\n        }] */\n        ...\n    })\n```\n\n## Response Language\n\nIt is possible to change the default language (English) of the description in the automatic response, for example, status code 404, the description will be: 'Not Found'. To change, pass an object with the following parameter:\n\n**English (by default)**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')();\n// In this case, for example, the description of status code 404 will be:\n// 'Not Found'\n```\n\nOR\n\n**Portuguese (Brazil)**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')({ language: 'pt-BR' });\n// In this case, for example, the description of status code 404 will be:\n// 'Não Encontrado'\n```\n\nOR\n\n**Chinese (Simplified)**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')({ language: 'zh-CN' });\n// In this case, for example, the description of status code 404 will be:\n// '未找到'\n```\n\nOR\n\n**Korean**\n\n```js\nconst swaggerAutogen = require('swagger-autogen')({ language: 'ko' });\n// In this case, for example, the description of status code 404 will be:\n// '찾을 수 없음'\n```\n\nFor now, the module only has the above languages.\n\n## Examples\n\nLinks to projects that cover the simplest use of this module as well as the most complete use. See the links below:\n\n[Example using Router](https://github.com/davibaltar/example-swagger-autogen-with-router)\n\n[Example without Router](https://github.com/davibaltar/example-swagger-autogen)\n\nSee the result after construction in the image below:\n\n![](https://raw.githubusercontent.com/davibaltar/public-store/master/screen-swagger-autogen.png)\n\n## Compatibility\n\nThis module is independent of any framework. For the recognition to be **automatic**, your framework must follow the pattern **foo.method(path, callback)**, where _foo_ is the variable belonging to the server or the route, such as _app_, _server_, _route_, etc. The _method_ are HTTP methods, such as to get, post, put, and so on. If the **foo.method(path, callback)** pattern is not found in the files, it will be necessary to **manually** enter the beginning and end of the endpoint using the `#swagger.start` and `#swagger.end` tags (see the section: [Forced Endpoint Creation](#forced-endpoint-creation)). If you use the _Express.js_ framework, the status code and produces will be automaticaly obtained according to the _status()_ and _setHeader()_ functions, respectively. If you use a framework that does not contain these functions, you will need to manually add them with the `#swagger.response[statusCode]` and `#swagger.produces` tags (see the [Responses](#responses) and [Consumes and Produces](#consumes-and-produces) sections).\n\n**Swagger version:** 2.0\n\n## Tutorials\n\nSome tutorials with examples:\n\n[Tutorial in English](https://medium.com/@davibaltarx/automatic-api-documentation-in-node-js-using-swagger-dd1ab3c78284)\n\n[Tutorial em Português Brasil](https://medium.com/@davibaltarx/documenta%C3%A7%C3%A3o-autom%C3%A1tica-de-apis-em-node-js-eb03041c643b)\n\n## Changelog\n\n- Version 2.0.x:\n  - Recognizes of Routes and referenced functions\n  - Endpoint with referenced callback now it's done automatically\n  - Multiple patterns now it's done automatically\n  - Partial TypeScript recognition\n  - Recognizes middleware and middleware array\n  - Code refactoring\n  - Bug fix\n- Version 2.1.x:\n  - Recognizes different file import patterns\n  - Recognizes some more features of TypeScript\n  - Bug fix\n- Version 2.2.x:\n  - Recognizes some more features of TypeScript\n  - Performance improvement\n  - Recognizes regex in endpoint's path\n  - Recognizes middlewares of routes (partially)\n  - Options to disable logs\n  - Bug fix\n- Version 2.3.x:\n  - Recognizes 'require-dir' lib (partially)\n  - Recognizes some more features of TypeScript\n  - Bug fix\n- Version 2.4.x:\n  - Recognizes direct import, such as: router.use(..., require('./routes.js'))\n  - Recognizes new Router({ prefix: '...' })\n  - Added some default parameters values\n  - Code refactoring\n  - Bug fix\n- Version 2.5.x:\n  - New tags: #swagger.summary and #swagger.operationId\n  - Bug fix\n- Version 2.6.x:\n  - Recognition of more patterns\n  - Bug fix\n- Version 2.7.x:\n  - Automatic body recognition\n  - Automatic 'destructuring' recognition (query and body)\n  - Bug fix\n- Version 2.8.x:\n  - OpenAPI option\n  - Code refactoring\n  - Bug fix\n- Version 2.9.x:\n  - Recognizes path with variables\n  - Recognizes regex in middlewares\n  - Bug fix\n- Version 2.10.x:\n  - Recognizes 'alias' in the import files\n  - New language\n  - Bug fix\n- Version 2.11.x:\n  - New tag: #swagger.requestBody\n  - Bug fix\n\n\n**TODO:**\n\n- Recognize more TypeScript's features\n- Recognize middlewares of routes (completely)\n- Recognize multiples \"express.Router()\" in the same file\n- Write more test cases\n- Improve performance\n- Refactor code\n- Integrate with other frameworks\n\n## Help us!\n\nHelp us improve this module. If you have any information that the module does not provide or provides incompletely or incorrectly, please use our [Github](https://github.com/davibaltar/swagger-autogen) repository.\n\n**pt-BR:**\nAjude-nos a melhorar este módulo. Se você tiver alguma informação que o módulo não forneça ou forneça de maneira incompleta ou incorreta, use o nosso repositório do [Github](https://github.com/davibaltar/swagger-autogen). Pode enviar em português Brasil também! :)\n\nRepository: https://github.com/davibaltar/swagger-autogen\n\n## License\n\n[MIT](LICENSE) License\n","readmeFilename":"README.md"}