用swagger生成api的接口文档（yaml版）

swagger的文档可以用json和yaml写，这里我用的yaml写的，会以文档+效果图表现出来：

swagger: "2.0"  
info:
  description: "this is a api for authenticating users and binding cloud accounts."
  version: "1.0.0"
  title: "Auth api"
 
host: "52.82.26.240:5000"

swagger: “2.0” 指定swagger的版本号
info: 关于该api的信息，版本和标题
host：表示你的ip地址或是域名

paths:
  /authenticate:
    post:
      tags:
      - "auth"
      summary: "Get a accessToken"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "body"
        description: "account of fastone"
        required: true
        in: "body"
        schema:
          $ref: "#/definitions/Auth"
      responses:
        400:
          description: "Invalid input"
        403:
          description: "Invalid credential"
        200:
          description: "Get a accessToken"

paths: 路由地址
post: 请求方法
tags: 命名空间
summary: 描述信息
consumes：消费格式‘application/json’和‘application/xml’
produces：生产格式‘application/json’和‘application/xml’
parameters：参数
name：参数名字
description：描述
required：是否必要
in：属于哪种参数 body, header, formData, query, path
body只能有一个，body里的参数需要以model的形式通过schema放在里面
schema:
$ref: “#/definitions/Auth”
$ref: 把model 在definitions里的Auth当作参数放入body中。
model Auth的写法，会放到yaml的最后

definitions:
  Auth:
    type: "string"
    properties:
      usernameOrEmail:
        type: "string"
      password: 
        type: "string"

responses：状态码
用swagger生成api的接口文档（yaml版）

/accounts/{usernameOrEmail}:
    get:
      tags:
      - "accounts"
      summary: "Finds all information by usernameOrEmail"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "accessToken"
        in: "header"
        required: true
        type: "string"
      - name: "usernameOrEmail"
        in: "path"
        description: "account of user that needs to be finded"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/User"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Invalid input"
        405:
          description: "Validation exception"

这里说下parameters，header是请求头，path是请求参数，可以有多个。
用swagger生成api的接口文档（yaml版）

最后把文件结构给出：
用swagger生成api的接口文档（yaml版）

python flask 自动生成api文档点击这里。
以上！

swagger editor 链接：swagger editor

用swagger生成api的接口文档（yaml版）

相关推荐