swaggerize-docs

1.0.0 • Public • Published

swaggerize-docs

NPM version Dependency Status Dev Dependency Status Code Climate Build Status Coverage Status

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

npm 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
// app.js
'use strict';
 
var path = require('path');
var express = require('express');
var swagger = require('swaggerize-express');
var swaggerDocs = require('swaggerize-docs');
var app = express();
 
var DOCS_PATH = path.join(__dirname, 'docs', 'main.yaml');
 
swaggerDocs(DOCS_PATH).then(function(api) {
  app.use(swagger({
    api: api,
    docspath: '/api-docs'
    handlers: './routes'
  }));
  app.listen(8000, function() {
    console.log('server started');
  });
});

Documentation:

# docs/main.yaml 
swagger: '2.0'
info:
  title: My API
  description: 'My API description'
  version: 1.0.0
paths:
  /users:
    $ref: './paths/users.yaml'
  /users/{id}:
    $ref: './paths/users/{id}.yaml'
definitions:
  User:
    $ref: './definitions/User.yaml'
# docs/paths/users.yaml 
get:
  summary: List Users
  description: Gets a list of users
  responses:
    200:
      description: Success
      schema:
        type: array
        items:
          $ref: '#/definitions/User'
# docs/paths/users/{id}.yaml 
get:
  summary: Get a User
  description: Gets a single user by id
  parameters:
    name: id
      in: path
      type: string
      required: true
      description: The Id of the user to get
  responses:
    200:
      description: Success
      schema:
        $ref: '#/definitions/User'
    404:
      description: Not Found
# docs/definitions/User.yaml 
properties:
  email:
    type: string
  createdAt:
    type: date
  updatedAt:
    type: date

Actual Routes:

// routes/users.js
'use strict';
 
var User = require('../models/user');
 
module.exports = {
  get: function(req, res, next) {
    User.find()
      .then(function(users) {
        res.json(users);
      })
      .catch(next);
  }
};
// routes/users/{id}.js
'use strict';
 
var User = require('../../models/user');
 
module.exports = {
  get: function(req, res, next) {
    User.findById(req.params.id)
      .then(function(user) {
        if (!user) { return res.sendStatus(404); }
        res.json(user);
      })
      .catch(next);
  }
};

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

Package Sidebar

Install

npm i swaggerize-docs

Weekly Downloads

0

Version

1.0.0

License

MIT

Last publish

Collaborators

  • ksmithut