web-dev-qa-db-ja.com

パラメータとして渡されたSwaggerオブジェクトは、swagger-uiでデフォルト値を持つことができますか？

MyObjectをパラメーターとして取るパスを定義します。 MyObjectには、猫と犬のプロパティがあります。これらにはデフォルト値があります。 swagger-editorでは、例にはデフォルト値が表示されていませんが、try-it-outは正しいデフォルトでMyObjectを作成します。

Swagger-uiでは、Modelsでデフォルトを確認できますが、APIでは確認できません。これらのデフォルトを設定する方法はありますか？ swagger： '2.0' info：title：パラメータの説明としてデフォルトのプロパティを持つオブジェクトを渡す：etc version： "Draft 0.1.1" Host：example.com basePath：/ produces：-application/json

paths:
  /myobject:

     post:
      summary: |
        post an object.
      parameters:
        - name: myObject
          in: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/MyObject'
      responses:
        200:
          description: OK

definitions:

  MyObject:  # move to/models/model.yml
      type: object
      description: Contains default properties
      required:
        - cats
        - dogs
      properties:
        cats:
          type: number
          default: 9
        dogs:
          type: string
          default: "fido"

swagger-editor api

swagger-ui API (try it out)

swagger-ui Models shows the default values

swagger-uiswagger-2.0swagger-editor
5
intotecho

defaultの使用法が間違っています。代わりにexampleが必要になるでしょう。

defaultはオプションのフィールドでのみ使用され、サーバー側で処理されますです。つまり、クライアントがペイロードに値を指定しない場合、サーバーはdefault値を使用します。

このUserモデルを考えてみましょう。

definitions:
  User:
    type: object
    required:
      - username
    properties:
      username:
        type: string
      role:
        type: string
        enum:
          - user
          - poweruser
          - admin
        default: user

roleプロパティはオプションであり、デフォルトはuserです。したがって、クライアントがroleなしでペイロードを送信する場合：

{
  "username": "bob"
}

サーバーはrole = userを想定します。


あなたの場合、フィールドの値の例を提供したいようです。これがexampleキーワードの目的です。

definitions:
  MyObject:
    type: object
    description: Contains default properties
    required:
      - cats
      - dogs
    properties:
      cats:
        type: number
        example: 9      # <---
      dogs:
        type: string
        example: fido   # <---
4
Helen

デフォルトには2種類あるようです。

  • サーバー側：変数は不要であり、変数が指定されていない場合、サーバーはその値を想定します OpenApi v3.0仕様からの定義
  • クライアント側：変数は必須であり、1つの値のみである必要があります（ヘッダーなど）

クライアント側のデフォルトの場合、required = Trueを設定し、enumを唯一の許可された値に設定することで定義できます。以下のこの例を参照してください。

swagger: "2.0"
info:
  title: "some api"
  description: "a description"
  version: "1.0.0"
Host: "example.com"
basePath: "/api"
schemes:
- "http"
paths:
  /myobject:
     post:
      summary: |
        post an object.
      parameters:
        - name: myObject
          in: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/MyObject'
      responses:
        200:
          description: OK
definitions:
  MyObject:
      type: object
      description: Contains default properties
      required:
        - cats
        - dogs
      properties:
        cats:
          type: number
          enum:
            - 9
        dogs:
          type: string
          enum:
            - fido

Swagger 2.0は、サーバーまたはクライアントの参照フレームを指定せずにデフォルトのパラメーターを最初に記述したため、デフォルトのパラメーターは少し混乱します。

Swagger 2.0仕様 スキーマのデフォルトを次のように定義します

default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)

OpenAPI v3.0仕様

default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
0
spacether