2

Swagger/OpenAPI (または、要求された機能をサポートする別の形式がある場合は同様のもの) を使用して指定された API で使用される JSON オブジェクトの拡張メタデータを宣言する方法を探しています。

アイデアは、このメタデータを使用して、このデータを編集するためのユーザー インターフェイスを自動的に/部分的に生成することです。

要求された機能のリスト:

  • 名前、説明、プレースホルダー、例などのユーザーが判読できる情報の多言語サポート – API 仕様自体の名前と説明は、CRUD エディターなどのエンド ユーザーに表示されるものとは異なる場合があります。

  • 検証メタデータ
    Swagger/OpenAPI には最小値、最大値、パターンなどのさまざまなフィールドがあることは知っていますが、検証用に特定の (多言語の) エラー メッセージを指定する方法はありません (「ユーザー名は文字と数字で構成する必要がある」など)。のみ」および複数の言語への翻訳)。または、一致する複数のパターン (それぞれに関連付けられた別のエラー メッセージ)。

    検証の別の方法は、独自の API 呼び出しである場合があります (電子メールまたはユーザー名が使用可能かどうかのチェックなど)。

  • リレーション メタデータ たとえば、ID フィールドは実際には別のオブジェクトの ID を (独自のメタデータと共に) 参照します。

4

1 に答える 1

3

OpenAPI (fka. Swagger) 仕様は、x-プロパティを使用して拡張できます ( Specification Extensionは仕様です)。これらのx-プロパティは、標準の OpenAPI パーサーでは無視されます。

JSONスキーマ定義であっても、仕様ファイルのほぼどこにでも独自のプロパティを定義できますが、それらを使用するには独自のパーサーを作成するか、Swagger UIなどのツールを変更して表示する必要があります(これはかなり簡単です)。それらをそのようなツールで。

定義にいくつかの x 張力を含む例を次に示します。

swagger: "2.0"

info:
  version: 1.0.0
  title: X-tension example
  description: Using x- properties to extend the OpenAPI specification
  x-example: we can put x-tension almost anywhere in the specification

paths: {}

definitions:
  User:
    properties:
      id:
        type: string
      name:
        type: string
        maxLength: 50
        minLength: 10
        x-validation:
          multiLingualMessage:
            en: Name's length must be between <minLength> and <maxLength>
            fr: La longeur de Name doit être comprise entre <minLength> et <maxLength>
      friends:
        type: array
        description: An array of UserId
        items:
          type: string
          x-reference:
            type: User

この OpenAPI 仕様は、エディターによって有効であると見なされx-ます。プロパティは無視されます。

この例はx-プロパティの説明にすぎず、質問に記載されているすべてのユース ケースを解決することを意図したものではありません。

于 2016-07-02T18:40:21.480 に答える