swagger-jsdoc-express
Parses JSDoc comments from files and strings and set ups Swagger UI from it, to be used with Express framework.
Last updated 3 days ago by mkloubertego .
LGPL-3.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install swagger-jsdoc-express 
SYNC missed versions from official npm registry.

npm

swagger-jsdoc-express

Sets up one or more Swagger documentation UIs via Express using JSDoc from source files.

Install

Execute the following command from your project folder, where your package.json file is stored:

npm install --save swagger-jsdoc-express

Example

Setup UI

import * as express from 'express';
import * as swaggerJSDocExpress from 'swagger-jsdoc-express';

const app = express();

// create a '/swagger' endpoint ...
swaggerJSDocExpress.setupSwaggerUIFromSourceFiles(
    {
        cwd: '/root/path/to/source/files',
        files: [ '**/*.ts', '**/*.js' ],
    },

    // ... and directly register it
    // in 'app'
    app
);

app.listen(8080, () => {
    // should be available via
    // http://localhost:8080/swagger
    // now
});

Document API

The following code shows, how to document API (you can put the JSDoc to all locations inside the files, which are handled by setupSwaggerUIFromSourceFiles() function):

/**
 * @swaggerDefinition
 *
 * MonitoringStatusResult:
 *   type: object
 *   properties:
 *     data:
 *       type: object
 *       description: The monitoring data (if operation was successful).
 *       properties:
 *         cpu_load:
 *           type: number
 *           description: The CPU load in percentage.
 *           example: 0.05
 *         database_connected:
 *           type: boolean
 *           description: Indicates if app could connect to database or not.
 *           example: true
 *         disk_space:
 *           type: number
 *           description: 'The total disc space, in bytes.'
 *           example: 509197923979
 *         disk_space_used:
 *           type: number
 *           description: 'The disc space in use, in bytes.'
 *           example: 23979
 *         ram:
 *           type: number
 *           description: 'The total ram, in bytes.'
 *           example: 5091979000
 *         ram_used:
 *           type: number
 *           description: 'The ram in use, in bytes.'
 *           example: 23979
 *         version:
 *           type: object
 *           description: The app version.
 *           properties:
 *             date:
 *               type: string
 *               description: The last commit date.
 *               example: '1979-09-05T23:09:19.790Z'
 *             hash:
 *               type: string
 *               description: The last commit hash.
 *               example: 0123456789012345678901234567890123456789
 *     success:
 *       type: boolean
 *       description: Indicates if operation was successful or not.
 *       example: true
 */
interface MonitoringStatusResult {
    // ...
}


/**
 * @swaggerPath
 *
 * /monitoring/status:
 *   get:
 *     summary: Returns monitoring data.
 *     produces:
 *       - application/json
 *     responses:
 *       '200':
 *         description: Operation was successful.
 *         schema:
 *           $ref: '#/definitions/MonitoringStatusResult'
 *       '500':
 *         description: Server error
 */
app.get('/monitoring/status', (request, response) => {
    return response.status(200)
        .send(JSON.stringify(<MonitoringStatusResult>{
            // ...
        }));
});

Instead of using YAML, you are also able to use JSON format.

Contributors

Documentation

The complete API documentation can be found here.

Resources

Current Tags

  • 2.4.0                                ...           latest (3 days ago)

17 Versions

  • 2.4.0                                ...           3 days ago
  • 2.3.0                                ...           15 days ago
  • 2.2.0                                ...           15 days ago
  • 2.1.3                                ...           15 days ago
  • 2.1.1                                ...           15 days ago
  • 2.1.0                                ...           15 days ago
  • 2.0.0                                ...           2 months ago
  • 1.5.0                                ...           2 months ago
  • 1.4.0                                ...           2 months ago
  • 1.3.1                                ...           3 months ago
  • 1.3.0                                ...           3 months ago
  • 1.2.0                                ...           3 months ago
  • 1.1.1                                ...           3 months ago
  • 1.1.0                                ...           3 months ago
  • 1.0.2                                ...           3 months ago
  • 1.0.1                                ...           3 months ago
  • 1.0.0                                ...           3 months ago
Maintainers (1)
Downloads
Today 0
This Week 18
This Month 126
Last Day 0
Last Week 0
Last Month 11
Dependencies (15)
Dev Dependencies (4)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |