如何在OpenAPI(Swagger)中使用方括号定义参数? [英] How to define parameters with square brackets in OpenAPI (Swagger)?

问题描述

我有一个带有使用方括号的查询参数的端点:

I have an endpoint with query parameters that use square brackets:

GET /info?sort[name]=1&sort[age]=-1

在这里，name和age是我的模型定义中的字段名称.

Here, name and age are the field names from my model definition.

如何为这些参数编写OpenAPI(Swagger)定义?

How can I write an OpenAPI (Swagger) definition for these parameters?

推荐答案

这取决于您使用的OpenAPI(Swagger)版本.

It depends on which version of OpenAPI (Swagger) you use.

可以将sort参数定义为具有name和age属性的对象.参数序列化方法应为style: deepObject和explode: true.

The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject and explode: true.

openapi: 3.0.0
...

paths:
  /info:
    get:
      parameters:
        - in: query
          name: sort
          schema:
            type: object
            properties:
              name:
                type: integer
                example: 1
              age:
                type: integer
                example: -1
          style: deepObject
          explode: true
      responses:
        '200':
          description: OK

Swagger UI 3.15.0+和Swagger-Editor 3.5.6+支持此功能.

This is supported in Swagger UI 3.15.0+ and Swagger-Editor 3.5.6+.

sort[name]和sort[age]需要定义为单独的参数:

sort[name] and sort[age] need to be defined as individual parameters:

swagger: '2.0'
...
paths:
  /info:
    get:
      parameters:
        - in: query
          name: sort[name]
          type: integer
        - in: query
          name: sort[age]
          type: integer
      responses:
        200:
          description: OK

这篇关于如何在OpenAPI(Swagger)中使用方括号定义参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！