用YAML生成Swagger格式的API Documentation

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了用YAML生成Swagger格式的API Documentation相关的知识,希望对你有一定的参考价值。

参考技术A 在工作当中,会遇到需要写API文档的情况。最开始,在网上搜现成的django-rest-swagger,用了之后发现,不是很好用,没办法一次成型的解决问题。后来,就直接本办法,把yaml转化成swagger的html,就是套django模板啦(render)。yaml语法和json宗旨是差不多的,都是list和dict的结合。swagger就是一种内容特定化的yaml文件。

YAML的view如下(一个view函数):

模板如下(html模板,替换字符串,记住要加 ‘|safe’):

YAML文件:

Swagger编写API文档的YAML中文示例

必要字段!Swagger规范版本,必须填2.0,否则该YAML将不能用于Swagger其他组件

swagger: \'2.0\'

必要字段!描述API接口信息的元数据

info:

接口标题

title: swagger说明文档 

接口文档的描述

description: 学习Swagger

版本号

version: 1.0.0

Swagger会提供测试用例,host指定测试时的主机名,如果没有指定就是当前主机,可以指定端口.

host: 127.0.0.1

定义的api的前缀,必须已/开头,测试用例的主机则为:host+bashPath

basePath: /api

指定调用接口的协议,必须是:"http", "https", "ws", "wss".默认是http.-表示是个数组元素,即schemes接受一个数组参数

schemes:

  • http
  • https

对应与http协议头request的Accept,调用者可接受类型,默认是/,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json

这两个是对所有接口的全局设置,在细化的接口中是还可以对应这两个属性来覆盖全局属性

produces:

  • application/json

必要字段!定义可有可操作的API

paths:
/users:

必要字段!定义HTTP操作方法,必须是http协议定义的方法

get:
  #接口概要
  summary: 查询所有用户信息
  #接口描述
  description: 查询出所有用户的所有信息,用户名,别名
  #标签,方便快速过滤出User相关的接口
  tags:
    - User
  #返回值描述,必要自动
  responses:
    #返回的http状态码
    200:
      description: 所有用户信息或者用户的集合信息
      #描述返回值
      schema:
        #返回值格式,可选的有array,integer,string,boolean
        type: array
        #针对array,每个条目的格式,type定义为array.必要填写items
        items:
          #引用在definitions下定义的Users
          $ref: \'#/definitions/User\'
    #执行出错的处理
    default:
      description: 操作异常,执行失败.返回信息描述错误详情
      schema:
        #值类型
        type: object
        #定义属性
        properties:
        #属性名
          message:
            #类型
            type: string
#即对于同一个url定义两个不同的方法,表示两个接口
post:
  description: 注册一个用户
  #请求参数
  parameters:
      #参数key
    - name: username
      #传递方法,formData表示表单传输,还有query表示url拼接传输,path表示作为url的一部分
      #body表示http头承载参数(body只能有一个,有body不能在有其他的)
      in: formData
      #参数描述
      description: 用户名,不能使用已经被注册过的
      #参数是否必要,默认false
      required: true
      #参数类型,可选的包括array,integer,boolean,string.使用array必须使用items
      type: string
    - name: password
      in: formData
      description: 用户登陆密码,加密传输,加密存储
      required: true
      type: string
    - name: alias
      in: formData
      type: string
      description: 用户别名
      #非必要字段
      required: false
  responses:
    #返回的http状态码
    200:
      description: 通过返回值来标示执行结果 返回true表示执行成功
      schema:
         #值类型
          type: object
          #定义属性
          properties:
          #属性名
            status:
              #类型
              type: boolean
              #描述
              description: 是否成功
    #执行出错的处理
    default:
      description: 操作异常,执行失败.返回信息描述错误详情
      schema:
        #值类型
        type: object
        #定义属性
        properties:
        #属性名
          message:
            #类型
            type: string

/users/{id}:
#{id}表示id为请求参数,例如/users/1,/users/2都是对该API的请求,此时id即为1和2
get:
summary: 根据用户名id查询该用户的所有信息
description: 查询出某个用户的所有信息,用户名,别名等
tags:
- User
parameters:
#上面接口中定义了{id},则参数列表中必须包含参数id,并且请求类型为path
- name: id
in: path
description: 要查询的用户的用户名,它是唯一标识
required: true
type: string
responses:
200:
description: 所有用户信息或者用户的集合信息
schema:
$ref: \'#/definitions/User\'
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#http定义的delete方法,删除一个资源
delete:
summary: 删除用户
description: 删除某个用户的信息,被删除的用户将无法登陆
parameters:
- name: id
in: path
type: string
required: true
description: 用户的唯一标示符
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#描述错误信息
#http定义的patch方法,表示修改一个资源
patch:
summary: 用户信息修改
description: 修改用户信息(用户名别名)
parameters:
- name: id
in: path
description: 用户名,要修改的数据的唯一标识符
required: true
type: string
- name: alias
in: formData
description: 新的用户别名
required: true
type: string
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#描述错误信息
definitions:
User:
#值类型
type: object
#定义属性
properties:
#属性名
id:
#类型
type: string
#描述
description: 用户的唯一id
username:
type: string
description: 用户名
alias:
type: string
description: 别名
————————————————
版权声明:本文为CSDN博主「u010466329」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/u010466329/article/details/78522992

以上是关于用YAML生成Swagger格式的API Documentation的主要内容,如果未能解决你的问题,请参考以下文章

使用 swagger 4.x 包生成 swagger 2.0 yaml

从现有的 JAVA Spring API 生成 YAML 文件

Swagger 可以根据现有的快速路由自动生成其 yaml 吗?

Swagger编写API文档的YAML中文示例

前端 怎么使用 swagger

python实现处理swagger接口文档,转换为yaml格式的自动化用例