Swagger从入门到放弃

如何编写基于OpenAPI规范的API文档

简介

• Swagger
• Swagger是一个简单但功能强大的API表达工具。支持的语言种类繁多
• 使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性
• OpenAPI规范
• OpenAPI规范是Linux基金会的一个项目，试图定义一种用来描述API格式或API定义的语言，来规范RESTful服务的开发过程
• OpenAPI可以帮助我们描述一个API的基本信息：
  • 有关API的一般性描述
  • 可用路径
  • 在每个路径上的可用操作
  • 每个操作的输入输出格式
• OpenAPI规范这类API定义语言能够更简单、快速的表述API，尤其是在API设计阶段作用比较明显
• 如何编写API文档
• 编辑器采用在线编辑：https://editor.swagger.io/#

•       swagger: "2.0"
        info:
        description: 
        version: "1.0.0"
        title: "Swagger Petstore"
        termsOfService: "http://swagger.io/terms/"
        contact:
            email: "apiteam@swagger.io"
        license:
            name: "Apache 2.0"
            url: "http://www.apache.org/licenses/LICENSE-2.0.html"
        host: "petstore.swagger.io"
        basePath: "/v2"
        tags:
        - name: "pet"
        description: "Everything about your Pets"
        externalDocs:
            description: "Find out more"
            url: "http://swagger.io"
        - name: "store"
        description: "Access to Petstore orders"
        - name: "user"
        description: "Operations about user"
        externalDocs:
            description: "Find out more about our store"
            url: "http://swagger.io"
        schemes:
        - "http"
        paths:
            /pet:
                post:
                tags:
                    - "pet"
                summary: "Add a new pet to the store"
                description: ""
                operationId: "addPet"
                consumes:
                    - "application/json"
                    - "application/xml"
                produces:
                    - "application/xml"
                    - "application/json"
                parameters:
                    -   in: "body"
                        name: "body"
                        description: "Pet object that needs to be added to the store"
                        required: true
                        schema:
                        $ref: "#/definitions/Pet"
                responses:
                    405:
                    description: "Invalid input"
                security:
                - petstore_auth:
                    - "write:pets"
                    - "read:pets"
  

从零开始

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    {}
  

• 显示界面如下：
• 
• 首先要通过swagger属性来声明OpenAPI规范的版本
• 然后需要说明API文档的相关信息，比如API文档版本、API文档名称、描述信息等
• 最后作为webURL，一个很重要的信息就是用来给消费者使用的 根URL ，可以使用协议http或https、主机名、根路径来描述：

      schemes: 
      - https
      host: simple.api
      basePath: /openapi101
      ```
  

• 接下来就是写API的操作，通过paths，然而这里没有写只是通过{}对象占用位置

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons:
        get:
        summary: Get some persons
        description: Returns a list containing all persons
        responses:
            200:
                description: A list of Person
                schema:
                    type: array
                    items:
                        required: 
                            - username
                        properties:
                            firstname:
                                type: string
                            lastname:
                                type: string
                            username:
                                type: string
  

• 在上面的这些代码中，做了以下的动作：
  1. 添加了/persons的路径，用来访问一组用户信息
  2. 在路径中添加了HTTP方法get，同时也有一些简单的描述信息summary和description
  3. 定义响应类型responses，响应类型中添加了HTTP状态码200
  4. 定义了响应内容：通过响应消息中的schema属性来描述清楚具体的返回内容。通过type属性可知一组用户信息就是一个用户信息数组，每一个数组元素则是一个用户对象，该对象包含三个string类型的属性，其中username必须提供（required）
• 定义请求参数

•   paths:
    /persons:
        get:
        summary: Get some persons
        description: Returns a list containing all persons
        parameters: 
            -   name: pageSize
                in: query
                description: Number of persons returned
                type: integer
            -   name: pageNumber
                in: query
                description: Page number
                type: integer
  

• 首先在get方法中添加了一个parameters属性
• 在参数列表中，添加了两个参数pageSize和pageNumber的整形参数，并有简单描述
• 定义路径参数

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons/{username}:
        get:
        summary: Get some persons
        description: Returns a list containing all persons
        parameters: 
            -   name: username
                in: path
                required: true
                description: The person's username
                type: string
            
        responses:
            200:
            description: A list of Person
            schema:
                type: array
                items:
                    required: 
                        - username
                    properties:
                        firstname:
                            type: string
                        lastname:
                            type: string
                        username:
                            type: string
  

• 路径参数、请求参数以及消息参数等的不同之处就在于in属性的值不同，分别为path、query、body等。同时对于参数的类型可以使用type或者schema来定义，例如消息体参数如下：

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
        /persons:
            post:
            summary: Creates a person
            description: Adds a new person to the persons list
            parameters: 
                -   name: person
                    in: body
                    description: The person to create
                    schema:
                        required: 
                        - username
                        properties:
                            firstname:
                                type: string
                            lastname:
                                type: string
                            username:
                                type: string
            responses:
                200:
                description: OK
  

• 如果是单个参数可以使用type进行定义例如integer，string ，array等，而如果是json类型的参数就需要使用schema类来定义。
• 定义相应消息

•   response:
        204:
            description:Persons successfully created
        400:
            description:Persons couldn't have been created
  

• 简化数据模型
• 通过使用definition来定义可重用的对象。如下：

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
    /persons:
        post:
        summary: Creates a person
        description: Adds a new person to the persons list
        parameters: 
            -   name: person
                in: body
                description: The person to create
                schema:
                    $ref: '#/definitions/Person'
        responses:
            200:
            description: OK
            schema:
                $ref: "#/definitions/Person"
            
    definitions:
        Person:
            required:
                - username
            properties:
                firstname:
                    type: string
                lastname: 
                    type: string
                username:
                    type: string
  

• 定义可重用的参数

•   swagger: '2.0'
    info:
    version: 1.0.0
    title: Simple API
    description: A simple API documentation
  
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    paths:
        /persons/{username}:
            get:
                parameters: 
                    - $ref: '#/parameters/username'
            
                responses:
                    200:
                    description: fsafsf
  
    parameters:
        username:
            name: username
            in: path
            required: true
            description: The person's username
            type: string
  

高级定义

• 字符串的长度和格式

•   -   name: username
        in: path
        required: true
        description: fasfsa
        type: string
        pattern: "[a-z0-9]{8,64}"
        minLength: 8
        maxLength: 64
  

• 日期和时间

•   parameters: 
        - name: dateofBirth
          in: query
          description: fasfsaf
          type: string
          format: date
  

• 枚举类型

•   code:
        type: string
        enum: 
            - DBERR
            - NTERR
            - UNERR
  

• 高级参数
• 参数的媒体类型
• 在文档的根节点下面添加：

•   produces:
        - text/xml
    consumes:
        - application/json
        - application/xml
  

• 高级响应消息
• 要定义一个不带消息体的相应消息，只需要写响应状态和描述即可

•   responses:
        '204':
            description: Person successfully created
  

• 与请求消息类似，必带参数使用required来标识

•   Person:
        required:
            - username
        properties:
            firstname:
                type: string
            lastname: 
                type: string
            username: 
                type: string
  

• 分类标签
• tags: - Persons