如何在 Asp.Net 核心 MVC 项目中显式定义 API Swagger 文档的控制器路径

Question

我正在开发一个 Asp.Net 核心 3.1 MVC 网络应用程序，其中包含网络 API 项目。现在我只想为 API 项目配置 Swagger 文档，那么如何在配置中指定仅使用 Web API 控制器来进行文档处理？

在ConfigureServices方法中启动classswagger的配置如下：-

services.AddSwaggerGen(option =>
{
    option.SwaggerDoc("v1.0",
        new OpenApiInfo
        {
            Title = "ProjName OpenApi",
            Version = "1.0",
            //Description = //get from appsettings.json
        });
    var xmlCommentFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlCommentFilePath = Path.Combine(AppContext.BaseDirectory, xmlCommentFileName);
    option.IncludeXmlComments(xmlCommentFilePath);
});

Configure方法中的配置如下：-

app.UseSwagger(option =>
{
    option.RouteTemplate = "docs/{documentname}/swagger.json";
});
app.UseSwaggerUI(option =>
{
    option.SwaggerEndpoint("/docs/v1.0/swagger.json", "ProjName OpenApi v1.0");
    option.RoutePrefix = "docs/v1.0";
    option.DocumentTitle = "ProjName OpenAPI Docs";
});

问题是 swagger gen 正在控制器文件夹、管理和身份区域中查找以生成文档，但我宁愿将其配置为仅使用 WebApi 文件夹中的控制器。在这些控制器中指定路由属性的所有控制器或操作方法也列在 API 文档中。我怎样才能排除这些？

有人可以帮我解决这个问题吗？我真的被困在这里了。

PS：我想提一下，我无法将 API 层移动到其单独的项目中。

Answer 1

根据您的描述，我建议您可以尝试创建一个自定义过滤器来检查控制器名称是否为 mvc 控制器，然后删除其路由。

更多详情，您可以参考以下代码：

Startup.cs ConfigureServices 方法：

        services.AddSwaggerGen(option =>
        {
            option.SwaggerDoc("v1.0",
new OpenApiInfo
{
    Title = "ProjName OpenApi",
    Version = "1.0"});
            option.DocumentFilter<HideInDocsFilter>();

        });

HideInDocsFilter

public class HideInDocsFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDescription in context.ApiDescriptions)
        {
             // replace the data to your controller name
            if (apiDescription.ActionDescriptor.DisplayName.Contains("Data"))
            {
                var route = "/" + apiDescription.RelativePath.TrimEnd('/');
                swaggerDoc.Paths.Remove(route);
            }
        }
    }
}

结果：

只包含 WeatherForecast 控制器方法

如何在 Asp.Net 核心 MVC 项目中显式定义 API Swagger 文档的控制器路径

How to explicitly define API Controllers Path for Swagger documentation in Asp.Net Core MVC Project

c#

asp.net

asp.net-core-mvc

asp.net-core-webapi

swagger-3.0