TP5集成Swagger编写API文档（二）

YAML语法

继续上篇内容

swagger editor 中左侧有大量的数据，有一些基本的属性我们要学习，所以学习swagger 是有一定成本的

先不管这些数据代表什么意思，我们首先看一下左侧的语法结构，摘要一部分如下

这种语法叫做 YAML，详细的介绍可以参见如下博客

YAML语法

这里只介绍基本语法规则

TP5集成Swagger编写API文档（二）

其值可以是字符串、对象、数组、引用等类型

有的同学问，可以使用json格式编写吗？当然可以，但是显然对于配置文件来说，YAML语法要比json简单很多，所以这里可以花费点功夫学习YAML语法

参数意义

理解了YAML语法结构后，就要了解左侧的参数到底都是什么意思，可以从头梳理

左侧其实就是Open API Spec，也就是编写的是OPEN API 的规范，也就是说我们按照这个规范来编写Open API

swagger：描述swagger 的版本信息
info：提供API的元数据，如API标题、介绍、开发者联系方式、版本信息等，这里的信息可以根据情况自行更改，也可以删除一些不需要的属性

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

下面是更改之后的数据结构

swagger: "2.0"
info:
  description: "本文档提供孤岛小程序所有API的说明"
  version: "1.0.0"
  title: "孤岛小程序API"
  termsOfService: "http://simple.cn/terms/"
  contact:
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

host：主机地址
basePath：相对于host的根路径

这两个数据组合到一起就是api的公共路径信息，如做出如下更改

host: "smple.cn"
basePath: "/v1"

最终所有api的请求路径都是 simple.cn/v1，修改之后，发现右侧的实时预览也发生了变化

TP5集成Swagger编写API文档（二）

tags：补充的元数据，在swagger ui中，用于作为api的分组标签

可以这样理解，比如我们提供了电影、音乐、图书三组api，tags属性就可以设置 movies music 和 book 三个值，这样有利于将所有api分组展示，以获取更加良好的展示

修改如下

tags:
- name: "book"
  description: "图书相关api"
- name: "music"
  description: "音乐相关api"
- name: "movies"
  description: "电影相关api"

TP5集成Swagger编写API文档（二）

另外，如果api非常简单，没有这么多分组，也可以删除 tags 属性

schemes，API的传输协议，http，https，ws，wss

注意，此项的值是一个数组，元素的顺序决定了api优先使用的协议

schemes:
- "http"
- "https"

paths：API的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作

示例描述了路径的写法，路径的写法要遵循api的命名规范

TP5集成Swagger编写API文档（二）

具体的api明明规范，单独一篇博客说明

HTTP 方法最常用的就是 post、get、put和delete

以/pet 为例，展开代码，其中参数的意义如下所示

TP5集成Swagger编写API文档（二）

大家注意，其中有几个参数我们有添加注解

consumes：规定向api发起请求时的MIME类型，只有符合这个类型api才会受理
produces：规定api返回响应时的MIME类型
security：验证，比较复杂，单独再说

另外，注意parameters 中的 schema 参数的值是

$ref: "#/definitions/Pet"

表示引用了definitions 中的 pet引用（引用也是YAML语法特性之一）

这里为什么使用引用？因为post 是新增一条数据，那么就需要向api提供一个对象，对象中的键值对可能很多，所以先在后面定义了一个Pet模型，然后再这里引用即可，有人说为什么不再这里定义，因为其他地方也需要引用这个模型

多说无益，下面根据自己的需求更改这个数据。途中标识出的是修改的地方

TP5集成Swagger编写API文档（二）

然后再定义一个Book模型

找到与 paths 同级别的 definitions，里面已经定义了几个模型

TP5集成Swagger编写API文档（二）

我们仿照其他模型的语法定义Book模型

TP5集成Swagger编写API文档（二）

到这里，一个api就配置好了

TP5集成Swagger编写API文档（二）

按照同样的方式配置其他api即可

完成配置

下面根据我自己的系统的实际需求，完成此文档的编写

1）去除api中的安全配置

2）删除不用的模型

3）删除其他不用的参数

下面是最终的配置文档

swagger: "2.0"
info:
  description: "本文档提供孤岛小程序所有API的说明"
  version: "1.0.0"
  title: "孤岛小程序API"
  termsOfService: "http://simple.cn/terms/"
  contact:
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "smple.cn"
basePath: "/v1"
tags:
- name: "book"
  description: "图书相关api"
- name: "music"
  description: "音乐相关api"
- name: "movies"
  description: "电影相关api"
schemes:
- "http"
- "https"
paths:
  /book:
    post:
      tags:
      - "book"
      summary: "新增一本书籍"
      description: ""
      operationId: "addBook"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "使用body方式传递的新增的书籍对象"
        required: true
        schema:
          $ref: "#/definitions/Book"
      responses:
        405:
          description: "Invalid input"
    put:
      tags:
      - "book"
      summary: "更新一本书籍信息"
      description: ""
      operationId: "updateBook"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "使用body方式传递的待更新的书籍对象"
        required: true
        schema:
          $ref: "#/definitions/Book"
      responses:
        400:
          description: "Invalid ID supplied"
        404:
          description: "Book not found"
        405:
          description: "Validation exception"
  /book/findByName:
    get:
      tags:
      - "book"
      summary: "根据名称查找书籍"
      description: "多个参数可以使用逗号分隔"
      operationId: "findBookByName"
      produces:
      - "application/json"
      parameters:
      - name: "name"
        in: "query"
        description: "要查找的书籍名称"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Book"
        400:
          description: "Invalid name value"
  /book/{bookid}:
    get:
      tags:
      - "book"
      summary: "根据id查找书籍"
      description: "返回一个书籍对象"
      operationId: "getBookById"
      produces:
      - "application/json"
      parameters:
      - name: "bookid"
        in: "path"
        description: "书籍id"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Book"
        400:
          description: "无效的书籍id"
        404:
          description: "Book not found"
    post:
      tags:
      - "book"
      summary: "更新书籍信息"
      description: "使用form data方式传递数据更新书籍信息"
      operationId: "updateBookWithForm"
      consumes:
      - "application/x-www-form-urlencoded"
      produces:
      - "application/json"
      parameters:
      - name: "bookid"
        in: "path"
        description: "待更新的书籍id"
        required: true
        type: "integer"
        format: "int64"
      - name: "name"
        in: "formData"
        description: "待更新的书籍名称"
        required: false
        type: "string"
      - name: "price"
        in: "formData"
        description: "待更新的书籍价格"
        required: false
        type: "string"
      responses:
        405:
          description: "Invalid input"
    delete:
      tags:
      - "book"
      summary: "删除一本书籍信息"
      description: ""
      operationId: "deleteBook"
      produces:
      - "application/json"
      parameters:
      - name: "api_key"
        in: "header"
        required: false
        type: "string"
      - name: "bookid"
        in: "path"
        description: "删除的书籍Id"
        required: true
        type: "integer"
        format: "int64"
      responses:
        400:
          description: "Invalid ID supplied"
        404:
          description: "Book not found"
  /book/{bookid}/uploadImage:
    post:
      tags:
      - "book"
      summary: "为书籍上传图片"
      description: ""
      operationId: "uploadFile"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - name: "bookid"
        in: "path"
        description: "上传图片的书籍id"
        required: true
        type: "integer"
        format: "int64"
      - name: "additionalMetadata"
        in: "formData"
        description: "上传到服务器的额外的数据"
        required: false
        type: "string"
      - name: "file"
        in: "formData"
        description: "上传的图片文件"
        required: false
        type: "file"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
definitions:
  Book:
    type: "object"
    properties: 
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
      price:
        type: "number"
  ApiResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      type:
        type: "string"
      message:
        type: "string"

TP5集成Swagger编写API文档（二）

YAML语法

参数意义

完成配置

相关推荐