swaggerize-docs

A complimentary swagger api docs that works especially well in conjunction with swaggerize-express.

NOTE: pre 1.0 did it a completely different way. This now is just a wrapper around swagger-parser with some default options in place.

Installation

1npm install swaggerize-docs --save

You should also read up on the Swagger spec.

Usage

In pre 1.0 versions, the directory structure was automatically loaded into your paths property for your api docs. In this version, it leverages the path dereferencing used by swagger-parser.

The following code snippets layout an app that looks like this:

project/
├─ app.js
├─ docs/
│  ├─ main.yaml
│  ├─ paths/
│  │  ├─ users.yaml
│  │  └─ users/
│  │     └─ {id}.yaml
│  └─ definitions/
│     └─ User.yaml
└─ routes/
   ├─ users.js
   └─ users/
      └─ {id}.js

1// app.js
2'use strict';
3
4var path = require('path');
5var express = require('express');
6var swagger = require('swaggerize-express');
7var swaggerDocs = require('swaggerize-docs');
8var app = express();
9
10var DOCS_PATH = path.join(__dirname, 'docs', 'main.yaml');
11
12swaggerDocs(DOCS_PATH).then(function(api) {
13  app.use(swagger({
14    api: api,
15    docspath: '/api-docs'
16    handlers: './routes'
17  }));
18  app.listen(8000, function() {
19    console.log('server started');
20  });
21});

Documentation:

1# docs/main.yaml
2swagger: '2.0'
3info:
4  title: My API
5  description: 'My API description'
6  version: 1.0.0
7paths:
8  /users:
9    $ref: './paths/users.yaml'
10  /users/{id}:
11    $ref: './paths/users/{id}.yaml'
12definitions:
13  User:
14    $ref: './definitions/User.yaml'

1# docs/paths/users.yaml
2get:
3  summary: List Users
4  description: Gets a list of users
5  responses:
6    200:
7      description: Success
8      schema:
9        type: array
10        items:
11          $ref: '#/definitions/User'

1# docs/paths/users/{id}.yaml
2get:
3  summary: Get a User
4  description: Gets a single user by id
5  parameters:
6    - name: id
7      in: path
8      type: string
9      required: true
10      description: The Id of the user to get
11  responses:
12    200:
13      description: Success
14      schema:
15        $ref: '#/definitions/User'
16    404:
17      description: Not Found

1# docs/definitions/User.yaml
2properties:
3  email:
4    type: string
5  createdAt:
6    type: date
7  updatedAt:
8    type: date

Actual Routes:

1// routes/users.js
2'use strict';
3
4var User = require('../models/user');
5
6module.exports = {
7  get: function(req, res, next) {
8    User.find()
9      .then(function(users) {
10        res.json(users);
11      })
12      .catch(next);
13  }
14};

1// routes/users/{id}.js
2'use strict';
3
4var User = require('../../models/user');
5
6module.exports = {
7  get: function(req, res, next) {
8    User.findById(req.params.id)
9      .then(function(user) {
10        if (!user) { return res.sendStatus(404); }
11        res.json(user);
12      })
13      .catch(next);
14  }
15};

API Configuration

swaggerDocs(docs, options)

• docs (String|Object) If a string is passed, it will read that as a filepath. If you pass on object, it will read that as your swagger docs object.

• options (Object) This is just the options object as documented here