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

Question

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

ConfigureServices 方法中启动类中 swagger 的配置如下：-

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>();

        });

隐藏文档过滤器

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 控制器方法