Swagger 2:在数组类型的查询参数中使用枚举引用 [英] Swagger 2: use enum reference in query parameter of array type

问题描述

无法获得如何在数组参数中使用带有枚举值的字符串类型的引用.我可以在 items 键中进行引用并且它正在工作，但是 Swagger 产生错误:不是有效的参数定义

Can not get how to use reference of string type with enum values in array parameter. I can make reference in items key and it is working, but Swagger produce error: Not a valid parameter definition

Web UI 生成界面，但它有 textarea 而不是我期望的多选框.

Web UI generates interface, but it have textarea instead of multiselect box I expected.

正确的做法是什么?

我的代码:

    swagger: '2.0':
    paths:
      /test:
        get:
          parameters:
          - in: origin
            name: status
            description: Origin
            required: false
            schema:
              type: array
              items:
                $ref: '#/definitions/Origin'
            collectionFormat: pipes'
    definitions:
      Origin:
        type: string
        description: Campaign origin
        enum:
          - one
          - two
    externalDocs:
      description: Find out more about Swagger
      url: http://swagger.io
    host: virtserver.swaggerhub.com
    basePath: /

推荐答案

items 包含 $ref 的数组参数是 不是 在 OpenAPI/Swagger 2.0 中支持.但看起来这将在下一个版本 3.0 中成为可能.目前有几种解决方法，见下文.

Array parameters with items containing $ref are not supported in OpenAPI/Swagger 2.0. But it looks like this will be possible in the next version, 3.0. For now there are a couple of workarounds, see below.

您的规范还有一些其他问题:

Your spec also has some other issues:

• in: origin 无效.in 关键字指定参数位置(路径、查询、标头等)，并且只接受 OpenAPI/Swagger 规范中的某些值.我猜你的意思是 in: query 或 in: header.

打字错误(或复制粘贴错误?):swagger: '2.0': 在末尾有一个额外的 : 和 collectionFormat: 管道' 在末尾有一个额外的 '.

Typos (or copy-paste errors?): swagger: '2.0': has an extra : at the end and collectionFormat: pipes' has an extra ' at the end.

具有包含枚举值的数组参数的一种解决方案是定义内联枚举:

One solution for having an array parameter containing enum values is to define the enum inline:

      parameters:
        - in: query
          name: status
          description: Origin
          required: false
          type: array
          collectionFormat: pipes
          items:
            type: string
            enum:
              - one
              - two

另一种解决方案(在此处)是使用用于引用枚举的 YAML 锚点.这是 YAML 的一项功能，您可以使用 &anchor-name 标记一个键，然后进一步使用 *anchor-name 来引用该键的值.

Another solution (found here) is to use YAML anchors to reference the enum. This is a feature of YAML where you can mark a key with &anchor-name and then further down use *anchor-name to reference that key's value.

definitions:
  Origin:
    type: string
    description: Campaign origin
    enum: &origin
      - one
      - two

paths:
  /test:
    get:
      parameters:
        - in: query
          name: status
          description: Origin
          required: false
          type: array
          collectionFormat: pipes
          items:
            type: string
            enum: *origin

这篇关于Swagger 2:在数组类型的查询参数中使用枚举引用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！