swagger的yaml编写规则

          in: query //参数的位置
          name: limit //参数的名字
          type: integer //类型
          required: false //是否必须
          default: 20 //默认
          minimum: 1 //最小值
          maximum: 100 //最大值
          description: The numbers of items to return. //参数的描述

in：

query parameters, such as /users?role=admin

path parameters, such as /users/{id}

header parameters, such as X-MyHeader: Value

body parameters that describe the body of POST, PUT and PATCH requests (see Describing Request Body)

form parameters – a variety of body parameters used to describe the payload of requests with Content-Type of application/x-www-form-urlencoded and multipart/form-data (the latter is typically used for file uploads)

查询参数，例如/user。role=admin

路径参数，如/用户/id

头参数，如x-myheader:值

描述POST、PUT和补丁请求的主体的主体参数(参见描述请求主体)

表单参数——用于描述应用程序/x-www格式的请求的有效负载的各种各样的body参数，包括urlen编码和多部分/表单数据(后者通常用于文件上传)。

        - in: query
          name: status
          type: string
          enum: [available, pending, sold] //参数的枚举 enum关键字允许您将一个参数值限制为一组固定的值。enum值必须是与参数类型相同的类型。

      # color=red,black,white
      parameters:
        - in: query
          name: color
          type: array
          collectionFormat: csv
          items:
            type: string

一个多值参数必须用类型:数组和适当的集合格式来定义。

collectionFormat指定数组格式(具有多个参数的单个参数或具有相同名称的多个参数)和数组条目的分隔符。

collectionFormat	Description	Example
csv (default)	Comma-separated values. 逗号分隔	foo,bar,baz
ssv	Space-separated values. 空格分隔	foo bar baz
tsv	Tab-separated values.	"foo\tbar\tbaz"
pipes	Pipe-separated values.	foo|bar|baz
multi	Multiple parameter instances rather than multiple values. This is only supported for the in: query and in: formData parameters.	foo=value&foo=another_value

        - in: query
          name: color
          required: false
          type: array
          minItems: 1 //最小数据项
          maxItems: 5 //最大项
          uniqueItems: true
          items:
            type: string
            enum: [black, white, gray, red, pink, orange, yellow, green, blue, purple, brown]

如果省略了这个参数，您还可以指定服务器将使用的默认数组:

        - in: query
          name: sort
          required: false
          type: array
          items:
            type: string
          default: ["-modified", "+id"]

        - in: query
          name: metadata
          required: true
          type: boolean
          allowEmptyValue: true  # <----- 允许空值

paths:
  /user/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

    get:
      summary: Gets a user by ID. 通过ID获取用户
      ...
    patch:
      summary: Updates an existing user with the specified ID. 使用指定的ID更新现有用户。
      ...
    delete:
      summary: Deletes the user with the specified ID.使用指定的ID删除用户。

For example, consider the /report endpoint that accepts either a relative date range (rdate) or an exact range (start_date+ end_date):

GET /report?rdate=Today
GET /report?start_date=2016-11-15&end_date=2016-11-20

You can describe this endpoint as follows:

paths:
  /report:
    get:
      parameters:
        - name: rdate
          in: query
          type: string
          description: >
             A relative date range for the report, such as `Today` or `LastWeek`.
             For an exact range, use `start_date` and `end_date` instead.
        - name: start_date
          in: query
          type: string
          format: date
          description: >
            The start date for the report. Must be used together with `end_date`.
            This parameter is incompatible with `rdate`.
        - name: end_date
          in: query
          type: string
          format: date //格式 binary 二进制 date 日期 
          description: >
            The end date for the report. Must be used together with `start_date`.
            This parameter is incompatible with `rdate`.
      responses:
        400:
          description: Either `rdate` or `start_date`+`end_date` are required.

  # Here, we override the "produces" array to specify other media types
  /logo:
    get:
      summary: Gets the logo image.
      produces: #API操作可以返回一个文件，比如图像或PDF。在这种情况下，用type:file定义响应模式，并在生成部分中指定适当的MIME类型。
        - image/png
        - image/gif
        - image/jpeg
      responses:
        200:
          description: OK

        type: "integer" # 参数类型 integer int 
        format: "int64" # 参数格式 int64 int32 date-time

相关文章：

 https://zhuanlan.zhihu.com/p/21353795

http://blog.csdn.net/yy8432113/article/details/53008143

http://swagger.io/specification/  //具体的数据格式文档

https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-5-advanced-input-and-output-modeling/

http://swagger.io/docs/specification/describing-parameters/