Использовать параметр запроса типа объекта в документации swagger

Question

У меня есть маршрут GET, где я хотел бы кодировать параметр объекта в url как строку запроса.

При написании документации чванства я в основном получаю ошибки, которые не позволяют мне использовать schema типы/object в параметре в query типа:

paths: 
    /mypath/: 
    get: 
     parameters 
     - in: path 
      name: someParam 
      description: some param that works 
      required: true 
      type: string 
      format: timeuuid #good param, works well 
     - $ref: "#/parameters/mySortingParam" #this yields an error 

parameters: 
    mySortingParam 
    name: paging 
    in: query 
    description: Holds various paging attributes 
    required: false 
    schema: 
     type: object 
     properties: 
     pageSize: 
      type: number 
     cursor: 
      type: object 
      properties: 
      after: 
       type: string 
       format: string 

Пары запроса запрос, имеющие значение объекта будет закодированы в реальном запросе ,

Несмотря на то, что в верхней части экрана отображается ошибка, объект визуализируется правильно в редакторе пользовательских интерфейсов swagger, однако эта ошибка распространяется поверх документации.

Answer 1

Я не думаю, что вы можете использовать «объект» в качестве параметра запроса в Swagger спецификации в качестве параметра запроса поддерживает только примитивный тип (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)

Answer 2

Это возможно, но только не с Swagger т.е. OpenAPI v2. OpenAPI v3 описывает, как это можно здесь:

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

parameters: 
- in: query 
name: filter 
# Wrap 'schema' into 'content.<media-type>' 
content: 
    application/json: # <---- media type indicates how to serialize/deserialize the parameter content 
    schema: 
     type: object 
     properties: 
     type: 
      type: string 
     color: 
      type: string 

В то же время вы могли бы просто иметь параметр запроса в виде простого старого типа строки, а затем выполнить сериализацию вручную, а затем установите параметр запроса в обязательный. Это то, что я делаю, пока SwaggerUI полностью поддерживает OpenAPI v3.