Swashbuckle 正在生成没有域类型信息的 Swagger 定义文件（缺少 #/definition/domain-type 部分）答案

【问题标题】：Swashbuckle is generating Swagger definition file without domain-type information (missing #/definition/domain-type part)Swashbuckle 正在生成没有域类型信息的 Swagger 定义文件（缺少 #/definition/domain-type 部分）
【发布时间】：2017-04-01 16:45:13
【问题描述】：

当我发布我的 Azure REST API 应用程序时，结果很奇怪

1）“所有”记录的获取方法按预期工作，生成如下：

public async Task<HttpOperationResponse<IList<DomainType>>> GetAllDomainObjectsWithOperationResponseAsync(...);

2) 对于Get by id、Update、Delete 和Create 方法，它是使用object 而不是域对象生成的

async Task<HttpOperationResponse<object>> DeleteDomainObjectByIdWithOperationResponseAsync(..)

因此，当我使用此 Delete、Update、Create 和 GetById 方法时，服务无法正常工作。如果我手动将object 替换为相应的域类型，它会按预期工作，但是在每次服务发布后，都会重新创建错误的代码...

我尝试了 SwaggerConfig.cs 中的一些东西（例如启用 IncludeParameterNamesInOperationIdFilter），但在这种情况下似乎没有帮助。

关于造成这种情况以及如何处理的任何想法？

附：我注意到一些更令人不快的行为——比如生成DateTime 为DateTimeOffset? 和byte 为byte[]，但我可以忍受。我不想经常打架的是通过所有生成的代码将object 类型更改为适当的域类型 - 在这种情况下编译器无能为力......

编辑

根据来自@olydis 的cmets，原来生成的swagger 定义文件缺少$ref, "#/definition/domain-type" 形式的返回类型定义。

在MVA course Mastering Azure App Service（模块 4。3:33 左右集成发现的演示）中是生成的 swagger 定义文件的可见示例，并且存在这些类型定义。什么可能导致 Swashbuckle 不生成此信息？我有一个最新的 Swashbuckle 版本 5.x.x。域类型是否必须满足任何先决条件才能使 Swashbuckle 正确生成 Swagger 文件？

Swagger definition file

编辑#2

当前的解决方法

在生成 REST API 客户端之前手动编辑生成的 swagger 定义文件

【问题讨论】：

如果这是 AutoRest 问题，如果您发布相应的 Swagger 文件，我可以重现（并帮助解决）此问题。另外，这听起来像是您自动生成的 Swagger？花花公子？如果是这样，请添加标签；-) 问题可能在于 Swashbuckle 生成错误的 Swagger - AutoRest 本身支持您在此处描述的内容
@olydis，嗨，谢谢！我添加了一个指向招摇定义文件的链接。它是在我发布我的 Azure REST API 应用程序时生成的 - 我已经在我的项目中添加了一个 Swashbuckle nuget 包，所以我猜它正在做这个 Swagger 生成的东西......我是这个 swagger/swashbuckle 的新手，所以也许这很容易......例如 - REST API 客户端中的 GetPromotionById 是使用对象而不是域对象生成的。但有趣的是——如果我在浏览器中大摇大摆地玩——那么这种方法是有效的。只有当我使用生成的 REST API 客户端时才会出现问题
在您提供的 Swagger 文件中，GetPromotionById 确实没有返回类型定义，因此 AutoRest 无法发明任何域类型来使用！我不是 Swashbuckle 方面的专家，但它显然没有生成足够详细地描述您的服务的 Swagger。 byte 和 byte[] 一样，实际上敲响了警钟，上次我遇到这个问题时，它是 Swashbuckle 的弃用版本！
@olydis 感谢您的想法！今天晚些时候我会检查一下。在浏览器中玩 swagger 的有趣部分 - 此方法返回正确的结果。
@olydis 原来我安装了最新的 Swashbuckle 和 Swashbuckle.Core (v5.5.3)，刚刚在他们的 github 页面上发布了一个问题 (/question)...我希望会有一些帮助...

标签： c# swagger swashbuckle azure-api-apps autorest

【解决方案1】：

您可以向 Swashbuckle 提供有关如何制定 Swagger JSON 文件的提示（fwiw - 现在有些人将 swagger 文档称为 Open API 文档）。

当我必须对我的 Web API 进行新的编辑时，这使我不必重新调整生成的代码

using Swashbuckle.Swagger.Annotations;

namespace MyCorp.WebApi.Controllers
{
  [Authorize]
  public class CrazyObjectController : ODataController
  {
    private MyDbModel db = new MyDbModel();

    [SwaggerResponse(HttpStatusCode.Created, Type = typeof(CrazyObject))]
    [SwaggerResponse(HttpStatusCode.BadRequest, Description = "Invalid Request")]
    [Authorize(Roles = "AdminAccess")]
    public async Task<IHttpActionResult> Post(CrazyObject crazObj)
    {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            db.CrazyObjects.Add(crazObj);
            await db.SaveChangesAsync();

            return Created(crazObj);
        }
  }
}

在上面的代码块中，魔法是通过属性行实现的： [SwaggerResponse(HttpStatusCode.Created, Type = typeof(CrazyObject))] 将这个 Type 与 201 响应代码相关联..

【讨论】：