SwashBuckle 不会生成符合 `swagger 2.0` 的 swagger.json答案

【问题标题】：SwashBuckle does not produce a swagger.json that is `swagger 2.0` compliantSwashBuckle 不会生成符合 `swagger 2.0` 的 swagger.json
【发布时间】：2020-05-21 16:46:32
【问题描述】：

我们正在使用 SwashBuckle 5.0 并尝试生成 swagger doc 2.0。显然，它确实产生了 swagger.json，它不是 100% 符合 swagger 2.0 规范。问题特别在于它如何获取枚举：

name: prop-name
description: something
type: array
items:
    $ref: '#/definitions/mytype'

它应该在哪里：

name: prop-name
description: something
type: array
items:
  type: string
  enum:
    - Item1

为了它是 100% swagger 2.0 规范。所以总结一下，SwashBuckle 为我们生成了一个 swagger.json，它不是 100% swagger 2.0 投诉。我们通过特别说明 SerializeAsV2 = true 来强制我们的配置使用 V2

我们还考虑升级到 OAS 3.0，并决定暂时放弃，因为所有客户端都必须更改，而且这是一项巨大的努力。所以我们回到试图弄清楚如何让 SwashBuckle 产生一个 100% 招摇 2.0 投诉的 swagger.json？我只是想看看在我向 SwashBuckle 团队提交错误之前是否不需要更改配置。

有什么建议吗？

【问题讨论】：

你试过升级到最新的 5.6.0 吗？
我用的是https://www.nuget.org/packages/Swashbuckle.AspNetCore/这里官方最新的是5.4.1。你在谈论 swashbuckle.Core 吗？那是一个不同的图书馆。
editor.swagger.io 没有将该模式标记为无效...

标签： swagger swagger-ui swagger-2.0 swashbuckle swashbuckle.aspnetcore

【解决方案1】：

我首先在http://editor.swagger.io 上快速测试您的模式，但没有收到任何错误...

这是我重现您的代码的尝试：
https://github.com/heldersepu/csharp-proj/blob/master/WebApi_NetCore/WebApi_NetCore/Controllers/ErrorController.cs#L19-L42

        [HttpPost]
        public List<MonthEnum> Enum(string id)
        {
            var l = new List<MonthEnum>();
            l.Add(MonthEnum.July);
            l.Add(MonthEnum.August);
            return l;
        }

那给我们：
https://raw.githubusercontent.com/heldersepu/hs-scripts/master/swagger/swagger_enum.json

    "/api/Error": {
        "post": {
          "tags": [
            "Error"
          ],
          ...
          "responses": {
            "200": {
              "description": "Success",
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/MonthEnum"
                }
              }
            }
          }
        }
      },
      ...
    },
    "definitions": {
      ...
      "MonthEnum": {
        "format": "int32",
        "enum": [
          0,
          1,
          ...
        ],
        "type": "integer"
      }
    }

Swagger UI 显示它有效：
http://petstore.swagger.io/?url=https://raw.githubusercontent.com/heldersepu/hs-scripts/master/swagger/swagger_enum.json

验证器没有任何错误：
https://validator.swagger.io/validator/debug?url=https%3A%2F%2Fraw.githubusercontent.com%2Fheldersepu%2Fhs-scripts%2Fmaster%2Fswagger%2Fswagger_enum.json

也许你的 swagger 架构中还有其他问题

【讨论】：