以下に定義するswagger 2.0リソースがあります。 「param1またはparam2」を必須にするにはどうすればよいですか?呼び出し元はparam1またはparam2を渡す必要があります。
/some/res:
put:
summary: some resource
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/SomeResponse'
parameters:
- name: param1
type: string
description: param1
in: formData
required: false
- name: param2
type: string
description: param2
in: formData
required: false
OpenAPI(fka Swagger)仕様は、条件付きパラメーターまたは相互に排他的なパラメーター(すべてのタイプ)をサポートしていません。
オープン機能のリクエストがあります:
クエリパラメータ間の相互依存関係のサポート
パラメータの説明 Swaggerドキュメントのパラメータ依存関係セクション:
Swaggerは、パラメーターの依存関係と相互に排他的なパラメーターをサポートしていません。 https://github.com/OAI/OpenAPI-Specification/issues/256 にオープン機能のリクエストがあります。
2017年6月の時点で、その問題には21の賛成票があり、プロジェクトで3番目に多くの賛同を得た問題となっています。
Swagger仕様は、条件付きの要件またはパラメーターの包含/除外をサポートしていません。
私が提案するのは、クエリパラメータの包含/除外のルールを説明で明確に述べることです。次に、言語に依存する検証フレームワーク(Javaのjavax.validation、restifyのrestify-validationなど)を使用して、それに応じてパラメーターを検証します。
この質問の特定のシナリオ-param1
またはparam2
のいずれかを含むフォームデータ本文を持つPOST/PUT/PATCHリクエストは、OpenAPI 3.0およびoneOf
を使用して定義できます。
openapi: 3.0.0
...
paths:
/some/res:
put:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- type: object
properties:
param1:
type: string
required:
- param1
additionalProperties: false
- type: object
properties:
param2:
type: string
required:
- param2
additionalProperties: false
Swagger UIユーザーへの注意:oneOf
スキーマのフォームデータUIとサンプルレンダリング 利用不可 OpenAPI 3.0定義はまだです。