.NET Core 2.1 上的 Swashbuckle/Swagger 自升级以来已停止工作

Question

我有一个 .NET Core 2.0 应用程序，使用 Swashbuckle/Swagger 生成 API 文档。当我们使用 2.1.0 预览版时，Swagger 运行良好。然后我们对 2.1.0 版本和 SDK 2.1.300 进行了大升级。我们没有注意到事情发生的确切时间，但现在我们的 Swagger 文档将无法加载。这是我们看到的：

项目引用了Swashbuckle.AspNetCore 2.5.0 版。 Startup.cs 中的相关代码如下。在ConfigureServices()：

services.AddSwaggerGen(swaggerOptions =>
{
    // Register a swagger doc
    swaggerOptions.SwaggerDoc("v1", new Info
    {
        // Optional descriptive info that will be included in the Swagger output
        Contact = new Contact
        {
            Name = "LightSail",
            Url = "https://myurl.com/"
        },
        Description = "A description of the API can go here",
        Title = "My API",
        Version = "v1"
    });

    // Xml file to get comment information from
    swaggerOptions.IncludeXmlComments("App_Data/Api.xml");
});

在Configure():

app.UseSwagger();

app.UseSwaggerUI(swaggerUiOptions => swaggerUiOptions.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1"));

我发现了很多其他类似的问题，其中一个表明可能存在重复的端点；我尝试添加对.ResolveConflictingEndpoints() 的呼叫，但这没有任何区别。我搜索了我的项目文件夹，没有名为swagger.json 的文件，所以我猜这就是问题所在。

任何想法为什么这不起作用，或者如何解决？

Answer 1

就我而言，我可以通过省略“。”来重现您的错误。像你所做的那样从终点开始。

如果我包含“.”，我不会收到错误。在路径的起点。 这是我的更多代码，以防万一。

在 ConfigureServices 我有

 services.AddSwaggerGen(c =>
    {
        c.OperationFilter<AuthorizationHeaderParameterOperationFilter>();

        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "My API",
            Description = "ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "my name",
                Email = "me@myemail.com"
            }
        });
    });

在配置中

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseAuthentication();

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();


    app.UseRewriter(new RewriteOptions()
        .AddRedirectToHttpsPermanent());

    app.UseSwagger(c =>
    {
        c.RouteTemplate =
            "api-docs/{documentName}/swagger.json";
    });
    app.UseSwaggerUI(c =>
    {
        //Include virtual directory if site is configured so
        c.RoutePrefix = "api-docs";
        c.SwaggerEndpoint("./v1/swagger.json", "Api v1");
    });

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            "default",
            "{controller=Home}/{action=Index}/{id?}");
    });

还有

public class AuthorizationHeaderParameterOperationFilter : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors;
            var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is AuthorizeFilter);
            var allowAnonymous = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is IAllowAnonymousFilter);

            if (isAuthorized && !allowAnonymous)
            {
                if (operation.Parameters == null)
                    operation.Parameters = new List<IParameter>();

                operation.Parameters.Add(new NonBodyParameter
                {
                    Name = "Authorization",
                    In = "header",
                    Description = "access token",
                    Required = true,
                    Type = "string"
                });
            }
        }

我的依赖是

Microsoft.AspNetCore.App (2.1.0)
Swashbuckle.AspNetCore (2.5.0)
Microsoft.NETCore.App (2.1.0)

Answer 2

这通常表示 Swashbuckle 出于某种原因不支持的控制器/操作。

预计您的项目中没有 swagger.json 文件。 Swashbuckle 使用 ASP.NET Core 的 ApiExplorer API 动态创建和提供服务。这里可能发生的是 Swashbuckle 无法生成 Swagger.json，因此 UI 无法显示。

正如 HelderSepu 所说，很难确切知道是什么导致了失败，因此最好的调试方法可能只是删除一半的控制器（只需将文件移动到临时位置）并检查问题是否仍然存在。然后你就会知道你的哪一半控制器包含了麻烦的动作。您可以“二进制搜索”删除控制器（然后是操作），直到找出导致 Swashbuckle 无法生成 Swagger.json 的操作方法。一旦你知道了，这应该是你代码中的一些问题还是应该在Swashbuckle repo 中提交的问题。

例如，Swashbuckle 似乎不支持开放泛型，因此具有像 [ResponseType(typeof(IEnumerable<>))] 这样的响应类型属性可能会导致这种行为。这也可能是路线不明确或类似绊倒 Swashbuckle 的问题。一旦您将失败的原因缩小到更具体的原因，就可以根据需要修复或归档。

Answer 3

我能够通过将 http 动词属性显式添加到我的 asp.net core 2.x 控制器方法来解决此错误。对于 Swashbuckle 来说，在方法名称前加上 http 动词的约定显然是不够的。

[HttpPost] public async Task<IActionResult> AddNewData([FromBody] MyType myType) { … }

Answer 4

我个人有点快，忘记在 Startup.cs 中的 ConfigureServices 方法中添加这一行。

services.AddSwaggerDocument();

Answer 5

就我而言，我错过了“HttpAttribute”：

public async Task<IEnumerable<ClientesListDto>> GetAll()
{
     return await _service.GetAllAsync();
}

那我就放了，大摇大摆的点赞：

[HttpGet]
public async Task<IEnumerable<ClientesListDto>> GetAll()
{
     return await _service.GetAllAsync();
}

Answer 6

今天发现可以在浏览器中直接去json url获取一些错误信息 例如

myapiurl/api/vi/swagger.json

Answer 7

就我而言，我有这个：

    [HttpGet("CleanUpSnoozedLeads")]
    public async Task<ActionResult<bool>> CleanUpSnoozedLeads()


    [HttpGet("CleanUpSnoozedLeads")]
    public async Task<ActionResult<bool>> DoSomethingElse()

请注意 HttpGet() 具有相同的名称。这也会导致未定义的错误。

Answer 8

一个非常常见的情况是模棱两可。例如，只需对两个 PUT 或 POST 操作使用相同的签名，就会得到错误。

Answer 9

其他答案对我不起作用。

当我尝试转到 swagger.json URL 位置时，我能够解决并理解我的问题：

https://localhost:XXXXX/swagger/v1/swagger.json

页面会显示错误和找不到的原因。

在我的例子中，我发现我的一种方法的 XML 定义配置错误，基于它返回的错误：

NotSupportedException: HTTP method "GET" & path "api/Values/{id}" overloaded by actions - ...
...
...

Answer 10

就我而言，我只是忘记在方法中添加 HttpPostAttribute 注释。

[HttpPost]
public ActionResult Post()
{
    return Ok();
}

Answer 11

在我的例子中，schemaId 存在冲突。显然，swagger JSON 中的每个类都必须有一个唯一的 schemaId。如果您在不同的命名空间中有两个具有相同名称的类，这将不起作用。我们必须在启动类中配置“UseFullTypeNameInSchemaIds”。 添加“options.CustomSchemaIds(x => x.FullName);”在“services.AddSwaggerGen”中 我通过在 VS 中启用输出窗口找到了跟踪，从下拉列表中的显示输出中选择主项目，然后访问 http://{yourapiendpoint}/swagger/v1/swagger.json

Answer 12

如果您的 api 具有相同的两个或多个 [HttpGet]，则它无法正常工作。 您应该指定 [HttpGet] ，[HttpGet ("{id}")] 简单的解决方案