swagger的yaml编写规则

来源：互联网发布：dnf韩服武神改版数据编辑：程序博客网时间：2024/06/07 06:11

          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指定数组格式(具有多个参数的单个参数或具有相同名称的多个参数)和数组条目的分隔符。
collectionFormatDescriptionExamplecsv (default)Comma-separated values. 逗号分隔foo,bar,bazssvSpace-separated values. 空格分隔foo bar baztsvTab-separated values."foo\tbar\tbaz"pipesPipe-separated values.foo|bar|bazmultiMultiple 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=TodayGET /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/

阅读全文

0 0