Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
swagger-jsdoc
Advanced tools
swagger-jsdoc - npm Package Compare versions
Comparing version 1.9.2 to 1.9.3
| { | ||
| "name": "swagger-jsdoc", | ||
| "version": "1.9.2", | ||
| "version": "1.9.3", | ||
| "description": "Generates swagger doc based on JSDoc", | ||
@@ -50,4 +50,4 @@ "main": "index.js", | ||
| "mocha-jshint": "^2.3.1", | ||
| "supertest": "^2.0.1" | ||
| "supertest": "^3.0.0" | ||
| } | ||
| } |
205
README.md
| # swagger-jsdoc | ||
| **swagger-jsdoc** enables to integrate [Swagger](http://swagger.io) using 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/). | ||
| [](https://www.npmjs.com/package/swagger-jsdoc) | ||
| [](https://www.npmjs.com/package/swagger-jsdoc) | ||
| [](https://gratipay.com/Surnet) | ||
@@ -14,180 +14,40 @@ [](https://circleci.com/gh/Surnet/swagger-jsdoc) | ||
| ## Supported Swagger Versions | ||
| * 2.0 | ||
| ## Goals | ||
| ## Install | ||
| **swagger-jsdoc** enables you to integrate [Swagger](http://swagger.io) | ||
| using [`JSDoc`](http://usejsdoc.org/) comments in your code. Just add `@swagger` on top of your DocBlock and declare the meaning of your code in `yaml` complying to the OpenAPI specification. | ||
| ```bash | ||
| $ npm install swagger-jsdoc --save | ||
| ``` | ||
| `swagger-jsdoc` will parse your documentation from | ||
| your actual living code and output an OpenAPI specification to integrate any server and client | ||
| technology as long as both sides comply with the specification. | ||
| ### Quick Start | ||
| Thus, the `swagger-jsdoc` project assumes that you want document your existing working code in a way to "give life" to it, generating a specification which can then be feeded into other Swagger tools, and not the vice-versa. | ||
| swagger-jsdoc returns the validated swagger specification as JSON. | ||
| 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) | ||
| ```javascript | ||
| var swaggerJSDoc = require('swagger-jsdoc'); | ||
| ## Supported versions | ||
| * [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (previously known as Swagger) | ||
| var options = { | ||
| swaggerDefinition: { | ||
| info: { | ||
| title: 'Hello World', // Title (required) | ||
| version: '1.0.0', // Version (required) | ||
| }, | ||
| }, | ||
| apis: ['./routes.js'], // Path to the API docs | ||
| }; | ||
| ## Install | ||
| // Initialize swagger-jsdoc -> returns validated swagger spec in json format | ||
| var swaggerSpec = swaggerJSDoc(options); | ||
| ```bash | ||
| $ npm install swagger-jsdoc --save | ||
| ``` | ||
| At this time you can do with the swaggerSpec whatever you want. | ||
| The simplest way would be serving it straight to the outside world: | ||
| Or using [`yarn`](https://yarnpkg.com/en/) | ||
| ```javascript | ||
| app.get('/api-docs.json', function(req, res) { | ||
| res.setHeader('Content-Type', 'application/json'); | ||
| res.send(swaggerSpec); | ||
| }); | ||
| ```bash | ||
| $ yarn add swagger-jsdoc | ||
| ``` | ||
| You could also use a framework like [swagger-tools](https://www.npmjs.com/package/swagger-tools) to serve the spec and a swagger-ui. | ||
| ### Quick Start | ||
| ### How to document the API | ||
| [Get started](./docs/GETTING-STARTED.md) by documenting your code. | ||
| The API can now be documented in JSDoc-style with swagger spec in YAML. | ||
| Note that `swagger-jsdoc` uses [node glob](https://github.com/isaacs/node-glob) module in the background when taking your files. This means that you can use patterns such as `*.js` to select all javascript files or `**/*.js` to select all javascript files in sub-folders recursively. | ||
| ```javascript | ||
| /** | ||
| * @swagger | ||
| * /login: | ||
| * post: | ||
| * description: Login to the application | ||
| * produces: | ||
| * - application/json | ||
| * parameters: | ||
| * - name: username | ||
| * description: Username to use for login. | ||
| * in: formData | ||
| * required: true | ||
| * type: string | ||
| * - name: password | ||
| * description: User's password. | ||
| * in: formData | ||
| * required: true | ||
| * type: string | ||
| * responses: | ||
| * 200: | ||
| * description: login | ||
| */ | ||
| app.post('/login', function(req, res) { | ||
| res.json(req.body); | ||
| }); | ||
| ``` | ||
| ### Example app | ||
| ### Re-using Model Definitions | ||
| A model may be the same for multiple endpoints (Ex. User POST,PUT responses). | ||
| In place of writing (or copy and pasting) the same code into multiple locations, | ||
| which can be error prone when adding a new field to the schema. You can define | ||
| a model and re-use it across multiple endpoints. You can also reference another | ||
| model and add fields. | ||
| ```javascript | ||
| /** | ||
| * @swagger | ||
| * definitions: | ||
| * NewUser: | ||
| * type: object | ||
| * required: | ||
| * - username | ||
| * - password | ||
| * properties: | ||
| * username: | ||
| * type: string | ||
| * password: | ||
| * type: string | ||
| * format: password | ||
| * User: | ||
| * allOf: | ||
| * - $ref: '#/definitions/NewUser' | ||
| * - required: | ||
| * - id | ||
| * - properties: | ||
| * id: | ||
| * type: integer | ||
| * format: int64 | ||
| */ | ||
| /** | ||
| * @swagger | ||
| * /users: | ||
| * get: | ||
| * description: Returns users | ||
| * produces: | ||
| * - application/json | ||
| * responses: | ||
| * 200: | ||
| * description: users | ||
| * schema: | ||
| * type: array | ||
| * items: | ||
| * $ref: '#/definitions/User' | ||
| */ | ||
| app.get('/users', function(req, res) { | ||
| res.json([ { | ||
| id: 1, | ||
| username: 'jsmith', | ||
| }, {1 | ||
| id: 2, | ||
| username: 'jdoe', | ||
| } ]); | ||
| }); | ||
| /** | ||
| * @swagger | ||
| * /users: | ||
| * post: | ||
| * description: Returns users | ||
| * produces: | ||
| * - application/json | ||
| * parameters: | ||
| * - name: user | ||
| * description: User object | ||
| * in: body | ||
| * required: true | ||
| * type: string | ||
| * schema: | ||
| * $ref: '#/definitions/NewUser' | ||
| * responses: | ||
| * 200: | ||
| * description: users | ||
| * schema: | ||
| * $ref: '#/definitions/User' | ||
| */ | ||
| app.post('/users', function(req, res) { | ||
| // Generate ID | ||
| req.body.id = Math.floor(Math.random() * 100) * 1 | ||
| res.json(req.body); | ||
| }); | ||
| ``` | ||
| ### Load external definitions | ||
| You can load external definitions or paths after ``swaggerJSDoc()`` function. | ||
| ```javascript | ||
| // Initialize swagger-jsdoc -> returns validated swagger spec in json format | ||
| var swaggerSpec = swaggerJSDoc(options); | ||
| // load external schema json | ||
| swaggerSpec.definitions.in_login = require("config/schemajson/in.login.schema.json"); | ||
| swaggerSpec.definitions.out_login = require("config/schemajson/out.login.schema.json"); | ||
| // or set manual paths | ||
| swaggerSpec.paths["api/v1/cool"] = {"get" : { ... } } | ||
| }; | ||
| ``` | ||
| ## Example App | ||
| There is an example app in the example subdirectory. | ||
@@ -206,17 +66,4 @@ To use it you can use the following commands: | ||
| ### Using a CLI | ||
| ### CLI | ||
| If the module is installed globally, a command line helper `$ swagger-jsdoc` will be available. | ||
| Otherwise `./bin/swagger-jsdoc` accesses to the same interface. | ||
| Common usage: | ||
| - Help menu: `./bin/swagger-jsdoc -h` | ||
| - Specify a swagger definition file: `./bin/swagger-jsdoc -d example/swaggerDef.js` - could be any .js or .json file which will be `require()`-ed and parsed/validated as JSON. | ||
| - Specify files with documentation: `./bin/swagger-jsdoc example/routes.js example/routes2.js` - free form input, can be before or after definition | ||
| - Specify output file (optional): `./bin/swagger-jsdoc -o output.json` - swagger.json will be created if this is not set. | ||
| If specifying an output file with a `.yaml` or `.yml` extension, the swagger spec will automatically be saved in YAML format instead of JSON. | ||
| - Watch for changes: `./bin/swagger-jsdoc -d example/swaggerDef.js example/routes.js example/routes2.js -w` - start a watch task for input files with API documentation. | ||
| This may be particularly useful when the output specification file is integrated with [Browsersync](https://browsersync.io/) | ||
| and [Swagger UI](http://swagger.io/swagger-ui/). Thus, the developer updates documentation in code with fast feedback in an | ||
| interface showing an example of live documentation based on the swagger specification. | ||
| You can also use the tool via [command line interface](./docs/CLI.md). It supports selecting multiple files, recursive subdirectories and watch task for continuous listening of changes in your code. |
No alert changes
Improved metrics
- Total package byte prevSize
- increased by295.16%
99204
- Number of package files
- increased by44.44%
13
Worsened metrics
- Number of lines in readme file
- decreased by-69.23%
68
No dependency changes