如何在 Swagger 中为 GET 参数指定示例? [英] How to specify examples for GET parameters in Swagger?

问题描述

我正在使用在线 Swagger Editor 为我的 API 创建 Swagger 规范.

I'm using the online Swagger Editor to create a Swagger spec for my API.

我的 API 有一个 GET 请求端点，我使用以下 YAML 代码来描述输入参数:

My API has a single GET request endpoint, and I'm using the following YAML code to describe the input parameters:

paths:
  /fooBar:
    get:
      tags:
        - foobar
      summary: ''
      description: ''
      operationId: foobar
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          type: string
          example: 123, FakeStreet
        - name: city
          in: query
          description: City of the Address
          required: true
          type: string
          example: New York

如果我输入 example 标签，我会收到一条错误消息:

If I put in the example tag, I get an error saying:

不完全是 <#/definitions/parameter> 中的一个，<#/definitions/jsonReference>

is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>

在 Swagger 中编写 GET 参数时如何设置示例?

How do I set an example when writing GET parameters in Swagger?

推荐答案

OpenAPI 2.0

OpenAPI/Swagger 2.0 没有用于非正文参数的 example 关键字.您可以在参数description 中指定示例.Swagger UI v2、v3.12+ 和 Dredd 等一些工具也为此目的支持 x-example 扩展属性:

OpenAPI 2.0

OpenAPI/Swagger 2.0 does not have the example keyword for non-body parameters. You can specify examples in the parameter description. Some tools like Swagger UI v2, v3.12+ and Dredd also support the x-example extension property for this purpose:

      parameters:
        - name: address
          in: query
          description: Address to be foobared. Example: `123, FakeStreet`.  # <-----
          required: true
          type: string
          x-example: 123, FakeStreet   # <-----

OpenAPI 3.0

OpenAPI 3.0 原生支持参数示例:

OpenAPI 3.0

Parameter examples are supported natively in OpenAPI 3.0:

      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          schema:
            type: string
            example: 123, FakeStreet   # <----
          example: 456, AnotherStreet  # Overrides schema-level example

这篇关于如何在 Swagger 中为 GET 参数指定示例?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！