Swagger使用文档

客官°小女子只卖身不卖艺 2022-07-12 05:41 284阅读 0赞

Swagger([http://swagger.io/docs/][http_swagger.io_docs])主要提供了三个功能:

>  *  Swagger Editor: Swagger提供的一个编辑器，用来通过Swagger提供的特定的YAML语法来编写API文档
>  *  Swagger Codegen: 代码生成器
>  *  Swagger UI: YAML语法定义我们的RESTful API，然后它会自动生成一篇排版优美的API文档，并且提供实时预览。

**我们只需要安装Swagger Editor就足够了，它基本上集成了其余两个工具**  
Swagger Editor通过远程服务器([http://editor.swagger.io][http_editor.swagger.io])也可以使用,但速度较慢，我们在本机安装。

### Swagger Editor的安装: ###

首先确保你的电脑安装了NodeJs环境。

npm install -g http-server
    wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
    unzip swagger-editor.zip
    http-server swagger-editor

运行成功后通过本机IP即可使用Swagger Editor,比通过Swagger服务器快的多。

### 在Swagger Editor中定义API ###

通过Swagger提供的特定的YAML语法来定义API,可以详细的描述API的方法,功能，参数，返回值等信息。现在通过一个简单的示例，学习编写Swagger的YAML文档以及生成服务端代码。

**通过Swagger定义登陆，注册，修改，删除四个RestFul接口:**

>  *  查询所有的User => /users　　　　　　　　　　　**使用get方法**
>  *  新增User => /users 　　　　　　　　　　　　　　　 **使用post方法**
>  *  根据某个id查询对应的User => /users/\{id\}　　　　　**\{id\}指定了你要查询的那个id,使用get方法**
>  *  根据某个id删除对应的User => /users/\{id\}　　　　　**\{id\}指定了要删除的那个id,使用delete方法**
>  *  修改某个id对应的User => /users/\{id\} 　　　　　　　**\{id\}指定了要修改的那个id,使用patch方法**  
>     一个完整的，可阅读的Swagger YAML的格式层次关系定义如下:

swagger:
    info:
      title:
      description:
      version:
    host: 
    basePath:
    schemes:
    produces:
    paths:
      /users:
        get:
          summary:
          description:
          tags:
          responses:
            httpResponseCode:
              description:
              schema:
            ...#与httpResponseCode同级，可描述多个状态吗
        post: 
          summary:
          description:
          tags:
          responses:
            httpResponseCode:
              description:
              schema:
            ...#与httpResponseCode同级，可描述多个状态吗
    
     　　...#与httpMethod同级，对于同一个URL可定义多个方法，表示不同的接口
      /users/{id}:
        delete:
          summary:
          description:
          tags:
          responses:
            httpResponseCode:
              description:
              schema:
            ...#与httpResponseCode同级，可描述多个状态吗
        patch:
          summary:
          description:
          tags:
          responses:
            httpResponseCode:
              description:
              schema:
            ...#与httpResponseCode同级，可描述多个状态吗

假设数据库中存在一个User表,表字段为\_id,username,password,alias。对该表定义出CURD操作接口

通过Swagger对于上述的接口编写文档，示例如下:

#必要字段！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即为１和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: 别名

![这里写图片描述][SouthEast]

![这里写图片描述][SouthEast 1]

### 生成代码 ###

**以Spring为例子:**  
　 点击Swagger Editor上方的generate server，点击Spring。则会根据该API描述生成一套基于Maven构建的Spring-Boot项目，通过安装相关依赖，运行mvn spring-boot:run则成功运行项目，相关的接口均可进行测试。**但这个mock server对于接口并没有返回值，如果需要一个完整的mock server还需要在此基础上使用其他工具集成。**

[http_swagger.io_docs]: http://swagger.io/docs/
[http_editor.swagger.io]: http://editor.swagger.io
[SouthEast]: /images/20220711/4df5fce72a6343d288a9b4e434f2786c.png
[SouthEast 1]: /images/20220711/bc796097476648ab9ef59102a8d2f29a.png