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:

1npm install --save swagger-jsdoc-express

Example

Setup UI

1import * as express from 'express';
2import * as swaggerJSDocExpress from 'swagger-jsdoc-express';
3
4const app = express();
5
6// create a '/swagger' endpoint ...
7swaggerJSDocExpress.setupSwaggerUIFromSourceFiles(
8    {
9        cwd: '/root/path/to/source/files',
10        files: [ '**/*.ts', '**/*.js' ],
11    },
12
13    // ... and directly register it
14    // in 'app'
15    app
16);
17
18app.listen(8080, () => {
19    // should be available via
20    // http://localhost:8080/swagger
21    // now
22});

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):

1/**
2 * @swaggerDefinition
3 *
4 * MonitoringStatusResult:
5 *   type: object
6 *   properties:
7 *     data:
8 *       type: object
9 *       description: The monitoring data (if operation was successful).
10 *       properties:
11 *         cpu_load:
12 *           type: number
13 *           description: The CPU load in percentage.
14 *           example: 0.05
15 *         database_connected:
16 *           type: boolean
17 *           description: Indicates if app could connect to database or not.
18 *           example: true
19 *         disk_space:
20 *           type: number
21 *           description: 'The total disc space, in bytes.'
22 *           example: 509197923979
23 *         disk_space_used:
24 *           type: number
25 *           description: 'The disc space in use, in bytes.'
26 *           example: 23979
27 *         ram:
28 *           type: number
29 *           description: 'The total ram, in bytes.'
30 *           example: 5091979000
31 *         ram_used:
32 *           type: number
33 *           description: 'The ram in use, in bytes.'
34 *           example: 23979
35 *         version:
36 *           type: object
37 *           description: The app version.
38 *           properties:
39 *             date:
40 *               type: string
41 *               description: The last commit date.
42 *               example: '1979-09-05T23:09:19.790Z'
43 *             hash:
44 *               type: string
45 *               description: The last commit hash.
46 *               example: 0123456789012345678901234567890123456789
47 *     success:
48 *       type: boolean
49 *       description: Indicates if operation was successful or not.
50 *       example: true
51 */
52interface MonitoringStatusResult {
53    // ...
54}
55
56
57/**
58 * @swaggerPath
59 *
60 * /monitoring/status:
61 *   get:
62 *     summary: Returns monitoring data.
63 *     produces:
64 *       - application/json
65 *     responses:
66 *       '200':
67 *         description: Operation was successful.
68 *         schema:
69 *           $ref: '#/definitions/MonitoringStatusResult'
70 *       '500':
71 *         description: Server error
72 */
73app.get('/monitoring/status', (request, response) => {
74    return response.status(200)
75        .send(JSON.stringify(<MonitoringStatusResult>{
76            // ...
77        }));
78});

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

Contributors

• m1h43l

Documentation

The complete API documentation can be found here.

Resources

• Swagger 2.0 defintion