23

時間を格納する単純な文字列を使用して、時間間隔の Swagger モデルを構築しようとしています (日時もあることがわかっています)。

definitions:
  Time:
    type: string
    description: Time in 24 hour format "hh:mm".
  TimeInterval:
    type: object
    properties:
      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"
      upperBound:
        $ref: "#/definitions/Time"
        description: Upper bound on the time interval.
        default: "24:00"

何らかの理由で、生成された HTML には、lowerBound と upperBound の「説明」が表示されず、元の Time の「説明」のみが表示されます。これは、私がこれを正しく行っていないと思います。

したがって、問題は、モデルをタイプとして使用することが、実際に私がやろうとしているようにできるかどうかです。

4

1 に答える 1

24

TL;DR:$ref兄弟は OpenAPI 3.1 でサポートされています。以前の OpenAPI バージョンでは、横にあるキーワード$refは無視されます。

OpenAPI 3.1

OpenAPI 3.1 に移行すると、定義は期待どおりに機能します。この新しいバージョンは、スキーマ内$refの兄弟を許可する JSON スキーマ 2020-12 と完全に互換性があります。

openapi: 3.1.0
...

components:
  schemas:
    Time:
      type: string
      description: Time in 24 hour format "hh:mm".

    TimeInterval:
      type: object
      properties:
        lowerBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Lower bound on the time interval.
          default: "00:00"
        upperBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Upper bound on the time interval.
          default: "24:00"

スキーマの外側 (たとえば、応答やパラメーター) では、$refs は兄弟summaryとdescriptionキーワードのみを許可します。これらの $ref に付随する他のキーワードは無視されます。

# openapi: 3.1.0

# This is supported
parameters:
  - $ref: '#/components/parameters/id'
    description: Entity ID

# This is NOT supported
parameters:
  - $ref: '#/components/parameters/id'
    required: true

OpenAPI 2.0 および 3.0.x

これらのバージョンでは、それ自体とそのすべての兄弟要素を、それが指している定義に$ref置き換えることによって機能します。それが理由です

      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

になる

      lowerBound:
        type: string
        description: Time in 24 hour format "hh:mm".

考えられる回避策は、ラップ$refすることです。これはallOf、属性を に「追加」するために使用できますが、$ref既存の属性を上書きすることはできません。

      lowerBound:
        allOf:
          - $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

別の方法は、$refをインライン定義に置き換えることです。

definitions:
  TimeInterval:
    type: object
    properties:
      lowerBound:
        type: string  # <------
        description: Lower bound on the time interval, using 24 hour format "hh:mm".
        default: "00:00"
      upperBound:
        type: string  # <------
        description: Upper bound on the time interval, using 24 hour format "hh:mm".
        default: "24:00"
于 2017-01-19T22:04:55.680 に答える