OpenAPI: come descrivere i parametri di query?

Question

Sto cercando di capire come documentare due dei miei parametri di query in OpenAPI.

Filtraggio

Il mio filtro segue le raccomandazioni di JSON: API , che assume la forma, ad esempio:

• ?filter[post]=1,2,3
• ?filter[post]=1,2,3&filter[author]=5

La filterchiave è un array associativo che può contenere un elenco di nomi di risorse nella mia API. Il valore assegnato a ciascuna chiave di filtro è un singolo ID o un elenco di ID separati da virgole.

Ordinamento

Per l'ordinamento segue anche la raccomandazione JSON: API , quindi qualcosa del genere:

• ?sort=age
• ?sort=age,-height

Al sortparametro della query viene assegnato il valore di un campo di ordinamento o di un elenco di campi di ordinamento separati da virgole. Nota che il segno meno che precede il heightcampo indica un ordinamento decrescente.

Domanda

Come rappresento il mio filtro e ordinamento in OpenAPI ?

Ad esempio, non sono sicuro che sia possibile specificare che la chiave del filtro è un array associativo o che accetta un elenco di ID separati da virgole. Quasi lo stesso problema per l'ordinamento: come rappresentare un elenco separato da virgole di campi di ordinamento?

Answer 1

Il seguente approccio dovrebbe aiutare

parameters:
  - in: query
    name: fields
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: string
        author:
          type: string
  - in: query
    name: sort
    schema:
      type: array
      items:
        type: string
        enum:
          - age
          - height

Una parte è simile alla domanda condivisa da @Helen. Ti consentirà di usarlo come nell'immagine sottostante

E il rispettivo comando cURL

curl -X GET "https://editor.swagger.io/user?filter[post]=1,2&filter[author]=3,4&sort=age&sort=height" -H  "accept: */*"

Puoi anche definire il filterparametro nel modo seguente

parameters:
  - in: query
    name: filter
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: array
          items:
            type: string
        author:
          type: array
          items:
            type: string

In questo modo l'interfaccia utente sarà più completa come di seguito

Quindi la richiesta cURL appare come di seguito

curl -X GET "https://editor.swagger.io/user?filter[post]=1&filter[post]=2&filter[author]=3&filter[author]=4&sort=age&sort=height" -H  "accept: */*"

E probabilmente non dovresti averne bisogno anyOfpoiché è correlato all'ereditarietà per situazioni in cui un metodo può restituire un oggetto della classe base o una qualsiasi delle sue sottoclassi.

Fare riferimento a oneof-anyof-allof-not - OpenAPI Specification per maggiori informazioni su di esso.