用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: 状态码

/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是请求参数,可以有多个。

最后把文件结构给出:

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

swagger editor 链接:swagger editor

相关推荐
©️2020 CSDN 皮肤主题: 技术黑板 设计师:CSDN官方博客 返回首页