Swagger

• The World's Most Popular API Tooling
• OpenAPI Specification
• простой инструмент для визуализации вашего RESTful API
• YAML-based
• написание API
• генерация из уже существующего
• кодогенерация

Swagger

http://swagger.io/
    

http://editor.swagger.io/#/
    

http://swagger.io/open-source-integrations/
    

Swagger

Swagger

swagger: "2.0"

info:
  title: News API
  version: "1.0.0"

host: news.xyz
schemes:
  - http
basePath: /api/v1

produces:
  - application/json
...
    

Swagger

...

paths:
  ...

definitions:
  ...
    

Swagger - Paths

/news:
  get:
    summary: Return news with paggination
    tags:
      - News
    parameters:
      - name: limit
        in: query
        type: number
        format: integer
      - name: offset
        in: query
        type: number
        format: integer
    responses:
      ...
    

Swagger - Paths

/news:
  get:
    ...
    responses:
      200:
        description: News portion
        schema:
          type: object
          properties:
            metadata:
              $ref: '#/definitions/Pagging'
            news:
              type: array
              items:
                $ref: '#/definitions/News'
      ...
    

Swagger - Paths

/news:
  get:
    ...
    responses:
      ...
      500:
        description: Server error
        schema:
          $ref: '#/definitions/Error'
    

Swagger

Swagger

Swagger - Paths

/news:
  post:
    summary: Create news
    tags:
      - News
    parameters:
      - name: token
        in: header
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/News'
    ...
    

Swagger - Paths

/news:
  post:
    ...
    responses:
      201:
        description: News created
        schema:
          $ref: '#/definitions/News'
      409:
        description: Already exist
        schema:
          $ref: '#/definitions/Error'
      500:
        description: Server error
        schema:
          $ref: '#/definitions/Error'
    

Swagger - Paths

/news/{id}:
  get:
    summary: Return one news item by id
    parameters:
      - name: id
        in: path
        required: true
        type: string
    responses:
      200:
        description: News item
        schema:
          $ref: '#/definitions/News'
      ...
    

Swagger - Paths

/news/{id}:
  get:
    ...
    responses:
      ...
      404:
        description: Not found
        schema:
          $ref: '#/definitions/Error'
      500:
        description: Server error
        schema:
          $ref: '#/definitions/Error'
    

Swagger - Paths

/news/{id}:
  put:
    summary: Update news
    tags:
      - News
    parameters:
      - name: token
        in: header
        required: true
        type: string
      - name: id
        in: path
        required: true
        type: string
      ...
    

Swagger - Paths

/news/{id}:
  put:
    ...
    parameters:
      ...
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/News'
    responses:
      200:
        description: News updated
        schema:
          $ref: '#/definitions/News'
      500: ...
    

Swagger - Paths

/news/{id}:
  delete:
    summary: Delete news
    tags:
      - News
    parameters:
      - name: token
        in: header
        required: true
        type: string
      - name: id
        in: path
        required: true
        type: string
    ...
    

Swagger - Paths

/news/{id}:
  delete:
    ...
    responses:
      200:
        description: News deleted
        schema:
          $ref: '#/definitions/News'
      500:
        description: Server error
        schema:
          $ref: '#/definitions/Error'
    

Swagger - Definitions

Error:
  type: object
  properties:
    error:
      type: object
      properties:
        message:
          type: string
        code:
          type: number
    

Swagger - Definitions

Pagging:
  type: object
  properties:
    count:
      type: number
      format: integer
    offset:
      type: number
      format: integer
    limit:
      type: number
      format: integer
    

Swagger - Definitions

News:
  type: object
  properties:
    id:
      type: number
      format: integer
    title:
      type: string
    content:
      type: string
    date:
      type: string
      format: date
    

Swagger - Codegen

https://github.com/krakenjs/swaggerize-express
    

Swagger - Codegen

npm install yo generator-swaggerize --save-dev
    

Swagger - Codegen

npx yo swaggerize
    

Swagger - Codegen

Swagger - Codegen

// server.js
var Http = require('http');
var Express = require('express');
var BodyParser = require('body-parser');
var Swaggerize = require('swaggerize-express');
var Path = require('path');

var App = Express();

var Server = Http.createServer(App);

App.use(BodyParser.json());
App.use(BodyParser.urlencoded({
    extended: true
}));
    

Swagger - Codegen

// server.js
App.use(Swaggerize({
    api: Path.resolve('./config/swagger.yaml'),
    handlers: Path.resolve('./handlers')
}));

Server.listen(8000, function () {
    App.swagger.api.host =
      this.address().address
      + ':'
      + this.address().port;

    console.log('App running on %s:%d',
      this.address().address,
      this.address().port);
});
    

Swagger - Codegen

// handlers/news.js
var dataProvider = require('../data/news.js');

module.exports = {
    get: function (req, res, next) {
      ...
    },
    post: function (req, res, next) {
      ...
    }
};
    

Swagger - Codegen

// handlers/news/{id}.js
var dataProvider
  = require('../../data/news/{id}.js');

module.exports = {
    get: function (req, res, next) {
      ...
    },
    put: function (req, res, next) {
      ...
    },
    delete: function (req, res, next) {
      ...
    }
};
    

Swagger - Codegen