如何在OpenAPI（Swagger）中定义枚举？

Question

如何在OpenAPI（Swagger）中定义枚举？

swaggerswagger-uiswagger-2.0openapi

83

有人知道如何在OpenAPI 2.0定义中定义可能的enum值，以便它们会显示在Swagger UI的模型选项卡中吗？
这里的示例有一个status属性的枚举选项。
如何在OpenAPI 2.0中定义这样的枚举？

- eloleon

4个回答

31

使用YAML语法进行更新。

OpenAPI 2.0：

parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    type: string
    enum:
      - 1
      - 2
    required: true

OpenAPI 3.0：

parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    schema:
      type: string
      enum:
        - 1
        - 2
    required: true

- Ricardo Souza

即使值是整数，它是否必须为“type：string”类型？ - theberzi

1

不需要。在那些例子中，我将字段定义为字符串类型，但如果你希望它们是其他类型，也可以。 - Ricardo Souza

-2

这应该可以工作：

{
    "name": "bookingType",
    "in": "path",
    "type": "array",
    "items": {
        "enum": [
            "packages", "accommodations"
        ]
    },
    "description": "lorem ipsum"
}

参考 https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject

- dstefanov

6

那实际上不是一个有效的定义。 "items" 对象必须在其中具有一个 "type" 属性才能有效。在您的示例中，"type": "string" 是适当的。翻译：这个定义其实是无效的。要使 "items" 对象有效，必须在其中包含一个 "type" 属性。在你的例子中，适合的是 "type": "string"。 - Ron

-3

这不是确切的答案，但在他们添加此功能之前，它可能适用于您。

只需像这样声明属性

"MyObject":{
   "properties":{
      "MyEnum":{
         "type":"Value1 or Value2 or Value3"
      }
   }
}

你的 ModelSchema 将显示 {}，但是 Model 将显示 MyEnum(Value1 或 Value2 或 Value3, 可选)

- Eulalie367

1

这不是OpenAPI/Swagger中“type”关键字的有效语法。 - Helen

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Ron · Accepted Answer

"enum" 在 OpenAPI 2.0 中的作用如下：

      {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "type": "string",
        "enum": [ "1", "2"],
        "required": true
      }

而在 OpenAPI 3.0 中：

      {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "schema": {
          "type": "string",
          "enum": [ "1", "2"]
        },
        "required": true
      }

您可以看到，有一个名为sample的查询参数，类型为字符串，并具有枚举指定两个可能的值。在此情况下，示例指示该参数是必需的，因此UI将不会显示空值作为选项。

要获取最小工作示例，请尝试以下内容：

{
  "swagger": "2.0",
  "info": {
    "title": "title",
    "description": "descriptor",
    "version": "0.1"
  },
  "paths": {
    "/sample": {
      "post": {
        "description": "sample",
        "parameters": [
          {
            "in": "query",
            "name": "sample",
            "description": "a sample parameter with an enum value",
            "type": "string",
            "enum": [
              "1",
              "2"
            ],
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request."
          }
        }
      }
    }
  }
}

要在本地测试它，您可以在JavaScript中声明一个变量（例如spec），并将其传递给SwaggerUi对象。

  var spec = { ... };

  window.swaggerUi = new SwaggerUi({
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",
    supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
    onComplete: function(swaggerApi, swaggerUi){
    ...

在这种情况下，url参数将被忽略。

最终输出结果如下：

enter image description here