swagger入门

优点

• 可调试
• 容易编写
• swagger 驱动api开发

开发流程

• swagger-editor：http://editor.swagger.io/ 或静态服务
• 生成user.yaml，如下面的示例，并放在静太服务器上
• swagger-ui:下载并放在静态服务上
• swagger-ui加上user.yaml

文档

• 关键字定义
• 参考1
• 参考2

示例

swagger: '2.0'
info:
  title: My Demo API
  description: 举个栗子，关于用户注册登录
  version: 1.0.0
  contact: 
    name: 王东文
    email: [email protected]
    url: http://www.meicai.cn
host: api.uber.com
schemes:
  - https
  - http
basePath: /v1
consumes:
  - application/x-www-form-urlencoded
produces:
  - application/json
paths:
  /user/login:
    get:
      summary: 用户登录
      description: |
        用户登录模块
      parameters:
        - name: username
          in: formData
          description: 用户名
          required: true
          type: string
          format: phone
        - name: password
          in: formData
          description: 密码
          required: true
          type: string
          format: password
      tags:
        - User
      responses:
        '200':
          description: 登录成功
          schema:
            $ref: '#/definitions/LoginOk'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  LoginOk:
    type: object
    properties:
      token:
        type: string
        description: 登录成功后，产生的访问token
      message:
        type: string
        description: 登录成功提示
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
        description: 错误码
      message:
        type: string
        description: 错误信息描述