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

Question

我正在开发一个ASP.NET Core3.1MVC web应用程序，里面有web API项目。现在我只想为API项目配置Swagger文档，那么如何在配置中指定只使用web API控制器进行文档？

ConfigureServices方法内startup类中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);
});

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";
});

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