如何在 OpenAPI (Swagger) 中定义枚举？

Posted 2023-02-16

【中文标题】如何在 OpenAPI (Swagger) 中定义枚举？

【英文标题】：How to define an enum in OpenAPI (Swagger)?

【发布时间】：2015-02-20 14:55:50

【问题描述】：

有谁知道如何在 OpenAPI 2.0 定义中定义可能的“枚举”值，以便它们显示在 Swagger UI 的“模型”选项卡中？此处的示例：https://petstore.swagger.io/#!/pet/addPet 具有 status 属性的枚举选项。如何在 OpenAPI 2.0 中定义这样的枚举？

【参考方案1】：

用 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

【参考方案2】：

"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 参数将被忽略。

最终，输出如下所示：

【讨论】：

嗨，韦伯伦。谢谢你的建议。仍然没有乐趣......无论我尝试什么，我仍然无法获得所有可能字符串的良好输出，如问题中提到的示例中 addPet 的“状态”。由于我遵循与此演示 json 相同的 JSON 模式 - petstore.swagger.wordnik.com/v2/swagger.json - 你能告诉我应该如何修改状态的宠物定义以达到与在线演示相同的结果吗？

使用哪个版本的 UI？当我测试它时，它运行良好。

我正在使用版本 2.0.47 并尝试在此示例中修改 json：github.com/swagger-api/swagger-ui/tree/master/dist。如果您可以修改此 json：petstore.swagger.wordnik.com/v2/swagger.json 并将其扔到网上某处，我将不胜感激

您查看的文件有误。改为检查 swagger-ui.js。

我的错 - 版本是 2.1.0-alpha.7，这似乎是最新的。你能在那个 github 例子中定义枚举吗？

【参考方案3】：

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

只需像这样声明属性

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

您的 ModelSchema 将显示 ，但模型将显示 MyEnum(Value1 or Value2 or Value3, optional)

【讨论】：

这不是 OpenAPI/Swagger 中 type 的有效语法。

【参考方案4】：

这应该可行：

    "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

【讨论】：

这实际上不是一个有效的定义。 “items”对象必须在其中具有“type”属性才有效。在您的示例中，"type": "string" 将是合适的。