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

Question

我正在开发一个 Asp.Net core 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 控制器方法