Modern Web 2018

進階補充版本 

by 劉艾霖

Outline

  • 其他應用場景

  • Mise

  • 2.0 ---> 3.0

  • 其他同類型的產品

  • Demo

其他應用場景

舊專案

  • swagger decorator 自動轉出文件
  • 透過 Swagger Inspector 匯出基礎版本的文件
export default class UserController {

  @apiRequestMapping("get", "/user/:id")
  @apiDescription("get user object by id, only access self or friends")
  @pathParameter({
    name: "id",
    description: "user id",
    type: "integer"
  })
  @queryParameter({
    name: "tags",
    description: "user tags, for filtering users",
    required: false,
    type: "array",
    items: ["string"]
  })
  @apiResponse(200, "get user successfully", User)
  static async getUserByID(ctx, next): User {
    ...
  }

}

Demo

簡易查詢後台

  • 測試寄信功能
  • 重寄報表
  • 查看狀態

Mise

swagger-jsdoc

/**
 * Represents a book.
 * @constructor
 * @param {string} title - 標題
 * @param {string} author - 作者
 */
function Book(title, author) {}
koa2-swagger-ui
const Koa = require('koa');
const koaSwagger = require('koa2-swagger-ui');
const app = new Koa();
 
app.use(
  koaSwagger({
    routePrefix: '/docs',
    swaggerOptions: {
      url: 'http://petstore.swagger.io/v2/swagger.json',
    },
  }),
);

swagger-js-codegen

var fs = require('fs');
var CodeGen = require('swagger-js-codegen').CodeGen;

var file = 'swagger/spec.json';
var swagger = JSON.parse(fs.readFileSync(file, 'UTF-8'));
var nodejsSourceCode = CodeGen.getNodeCode({ className: 'Test', swagger: swagger });
var angularjsSourceCode = CodeGen.getAngularCode({ className: 'Test', swagger: swagger });
var reactjsSourceCode = CodeGen.getReactCode({ className: 'Test', swagger: swagger });
var source = CodeGen.getCustomCode({
    moduleName: 'Test',
    className: 'Test',
    swagger: swaggerSpec,
    template: {
        class: fs.readFileSync('my-class.mustache', 'utf-8'),
        method: fs.readFileSync('my-method.mustache', 'utf-8'),
        type: fs.readFileSync('my-type.mustache', 'utf-8')
    }
});

Readme.IO

CORS

app.use('*', function(req, res, next) {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, OPTIONS');
    res.header('Access-Control-Allow-Headers', 'Accept, Origin, Content-Type');
    res.header('Access-Control-Allow-Credentials', 'true');
  next();
 });

2.0 ---> 3.0 更動的部分

Common Mark

  • Github Flavored Markdown (GFM) ---> Common Mark

parameters body

parameters:
  - in: "body"
    name: "body"
    description: "新增 Pet object"
    required: true
    schema:
      $ref: "#/definitions/Pet"
requestBody:
  $ref: '#/components/requestBodies/Pet'

2.0

3.0

 新增 Link Object

  • 新增 Link 類似  HATEOAS

Multiple Servers

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

Multiple Servers

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider.
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # special base paths as assigned by the provider, default is `v2`
      default: v2

more components

components: # 可以重複使用的元件
    schemas: {}
    parameters: {}
    responses: {}
    securitySchemes: {} # 認證 schemes

2.0 ---> 3.0 更動的部分

  • Github Flavored Markdown (GFM) ---> CommonMark

  • parameters body 被獨立成 requestBody

  • 新增 Link 類似  HATEOAS

  • Multiple Servers

  • more components

資料來源：A Visual Guide to What's New in Swagger 3.0

https://github.com/Mermade/oas-kit

其他同類型的產品

  • API Blueprint

    • 基於 Markdown

  • Raml

  • Postman

  • apidoc

更多資源

Demo

https://github.com

/alincode/modern-web-2018-swagger

總結

Modern Web 2018 - 進階補充版本

By alincode

Made with Slides.com

Modern Web 2018 - 進階補充版本

by alincode

  • 1,183

More from alincode