13

私は Scala で Swagger を使用して、REST API を文書化しています。POST、PUT、および DELETE の一括操作を有効にし、同じルートで単一のオブジェクトまたはオブジェクトのコレクションを本文コンテンツとして受け入れるようにしたいと考えています。

パラメータがタイプAの値のリストまたはタイプAの単一の値であることをSwaggerに伝える方法はありますか?

REST の可変引数のようなもの。

4

3 に答える 3

16

パラメータがタイプAの値のリストまたはタイプAの単一の値であることをSwaggerに伝える方法はありますか?

これは、OpenAPI 3.0 と OpenAPI (Swagger) 2.0 のどちらを使用するかによって異なります。

OpenAPI は、JSON スキーマの拡張サブセットを使用して本文ペイロードを記述します。JSON スキーマは、インスタンスに対して複数の可能なスキーマを定義するキーワードoneOfとキーワードを提供します。anyOfただし、OpenAPI のバージョンが異なれば、サポートされる JSON スキーマ キーワードのセットも異なります。

OpenAPI 3.0 ではoneOfとがサポートanyOfされているため、このようなオブジェクトまたはオブジェクトの配列を次のように記述できます。

openapi: 3.0.0
...

components:
  schemas:
    A:
      type: object
    Body:
      oneOf:
        - $ref: '#/components/schemas/A'
        - type: array
          items:
            $ref: '#/components/schemas/A'

上記の例でBodyは、 objectAまたは objects の配列のいずれかになりますA。

OpenAPI (Swagger) 2.0は と をサポート していませんoneOfanyOf。できることのほとんどは、型のないスキーマを使用することです:

swagger: '2.0'
...

definitions:
  A:
    type: object
  # Note that Body does not have a "type"
  Body:
    description: Can be object `A` or an array of `A`

これはBody、オブジェクト (任意のオブジェクト!)、配列 (任意の項目を含む!)、プリミティブ (文字列、数値など) など、何でもかまいません。Bodyこの場合、正確な構造を定義する方法はありません。これは、口頭でのみ説明できますdescription。

正確なシナリオを定義するには、OpenAPI 3.0 を使用する必要があります。

于 2015-08-03T06:12:38.693 に答える
4

Swagger でそのような API に注釈を付けることが可能かどうかはわかりません。しかし、私の提案は、API を簡素化/統合することです。考えてみれば、バルク (オブジェクトの配列を意味する) をサポートするつもりなら、単一のオブジェクトを特別に扱う理由はありません。常に配列を取るように API を変更する必要があります。誰かが単一のオブジェクトを実行したい場合は、単一の要素を持つリストの場合ですobject :: Nil。

于 2015-07-31T21:15:32.820 に答える