Swagger2从零开始

Posted 2021-02-13 itmeatball

2.1从一个最简单的API文档开始

#声明OPENAPI规范的版本

swagger:"2.0"

#声明API相关信息，如版本信息、描述信息            

info:

  version:1.0.0

  title:Simple API

  description:A simple API to learn how to write OpenAPI Specification

#提供消费者根URL让消费者可以根据这个URL来访问根下的所有API

schemes:

  -https                                        #规定可用协议

host:rui.api                                 #主机

basePath:/openai101                 #根路径

#定义一个API的操作

paths: 

      /persons:                                                                                             #添加一个/person的路径，用来访问一组用户信息

       get:

          summary:Gets some persons

          description:Returns a list containing all persons.                           #在路径中添加一个HTTP动词来操作所需要的资源,这样一来我们调get https://rui.api/openapi/101/persons 就可以获取一组用户信息了

          responses:                                                                                     #响应类型通过状态码来定义，如200 OK 404 not found

             200:                                                         

                description:A list of Person

                schema:                                                                                    #定义响应内容，通过返回消息中的schema属性来描述清楚具体的返回内容

                    type:array

                    items:

                        required:

                             -username

                        properties:

                            firstName:

                                  type:string

                            lastName:

                                   type:string

                            userName:

                                   type:string

 

 

2.2定义请求参数

#在get方法中增加请求参数: 

        paths:

                   /persons:

                       get:

             summary: Gets some persons

            description: Returns a list containing all persons. The list supports paging. 

              #在get方法中添加分页参数，这样消费者可以通过get /persons?pageSize=20&pageNumber=2来访问第2页的用户信息

           parameters:                                                       

         - name: pageSize
           in: query
           description: Number of persons returned
           type: integer
        - name: pageNumber
          in: query
          description: Page number
          type: integer

2.3定义路径参数

  /persons/{username}:  #添加一个/persons/{username}的接口操作来获取指定username的用户信息，其中{username}是路径请求中的参数
    get:
      summary: Gets a person
      description: Returns a single person for its username
      parameters:
        - name: username                       #因为{username}是路径参数，我们需要像请求参数一样将它添加到parameters属性中
          in: path                             #通过in来表示这是一个路径参数
          required: true
          description: The person‘s username
          type: string
      responses:
        200:
          description: A Person
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
        404:
          description: The Person does not exists.

2.4定义响应消息

      responses:
        200:
          description: A Person
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string

2.5定义消息体参数

    post:
      summary: Creates a person
      description: Adds a new person to the persons list.
      parameters:
        - name: person
          in: body                               #通过in属性说明该参数是在body消息体中的
          description: The person to create.
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
      responses:
        204:
          description: Persons succesfully created.
        400:
          description: Persons couldn‘t have been created.