Skip to content
This repository has been archived by the owner on May 2, 2024. It is now read-only.

Parses JSDoc comments from files and strings and sets up Swagger UI from it, which can be used with Express.js framework.

License

Notifications You must be signed in to change notification settings

egodigital/swagger-jsdoc-express

Repository files navigation

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

Releases

No releases published

Packages

No packages published