作为参数传递的 swagger 对象可以在 swagger-ui 中具有默认值吗?

问题描述

我定义了一个以 MyObject 作为参数的路径.MyObject 具有猫和狗的属性.这些有默认值.在 swagger-editor 中，该示例未显示默认值，但试用确实创建了一个具有正确默认值的 MyObject.

I define a path that takes MyObject as a parameter.MyObject has properties for cats and dogs. These have default values.In swagger-editor, the example doesn't show the default values, but try-it-out does create a MyObject with correct defaults.

在 swagger-ui 中，我可以在 Models 下看到默认值，但在 API 中看不到.有没有办法设置这些默认值?招摇:'2.0'信息:标题:将具有默认属性的对象作为参数传递说明:等版本:草案 0.1.1"主机:example.com基本路径:/产生:- 应用程序/json

In swagger-ui, I can see the defaults under Models, but not in the API. Is there a way to set these defaults ? swagger: '2.0' info: title: pass object with default properties as a parameter description: 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"

推荐答案

您对 default 的使用是错误的.您可能需要 example 代替.

Your usage of default is wrong. You probably want example instead.

default 仅用于可选字段，并且在服务器端处理.也就是说，如果客户端未在有效负载中提供值，则服务器将使用 default 值.

default is only used with optional fields and is handled on the server side. That is, if the client does not supply a value in the payload, the server will use the default value.

考虑这个 User 模型:

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

role 属性是可选的，默认为 user.所以，如果客户端发送没有 role 的负载:

The role property is optional and defaults to user. So, if the client sends the payload without role:

{
  "username": "bob"
}

服务器将承担角色=user.

在您的情况下，您似乎想要为字段提供示例值.这是 example 关键字的用途:

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

这篇关于作为参数传递的 swagger 对象可以在 swagger-ui 中具有默认值吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！