如何为含API与OData的C#项目生成指定API的Swagger文档？

一、用Swagger生成指定API文档的方法 #

1. 通过代码过滤指定API #

在项目的Swagger配置中添加自定义文档过滤器，只保留你需要的API路径：

// 在Program.cs/Startup.cs的Swagger配置中
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "精简API文档", Version = "v1" });
    c.DocumentFilter<SelectSpecificApisFilter>();
});

// 自定义过滤器类
public class SelectSpecificApisFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 定义需要保留的API路径规则，比如指定控制器或OData实体路径
        var allowedPaths = swaggerDoc.Paths
            .Where(p => p.Key.StartsWith("/api/YourTargetController") 
                     || p.Key.Contains("/odata/YourODataEntity"))
            .ToList();

        swaggerDoc.Paths.Clear();
        foreach (var path in allowedPaths)
        {
            swaggerDoc.Paths.Add(path.Key, path.Value);
        }
    }
}

启动项目后，Swagger UI只会显示你指定的API，导出的JSON也会大幅精简。

2. 用独立JSON生成指定API #

如果你已经有单独的OpenAPI规范JSON文件（只包含需要的API定义），可以用Swagger CLI工具处理：

• 安装Swagger CLI：npm install -g swagger-cli
• 打包指定的JSON文件生成完整文档：swagger-cli bundle your-specific-api.json -o trimmed-swagger.json

二、其他适用工具 #

• NSwag：与Swagger生态兼容，支持通过配置文件（nswag.json）精确指定要包含的控制器、操作，也能通过命令行直接生成指定范围的API文档，还支持导出为HTML、PDF等格式。
• ApiDoc：轻量级工具，通过代码注释中的@api标记指定要生成文档的API，无需依赖项目的Swagger配置，适合快速生成部分API的文档。
• Postman：将项目完整Swagger导入Postman后，选中需要的API集合，直接导出为HTML或JSON格式的文档，操作简单，可视化程度高。

内容的提问来源于stack exchange，提问作者Vitaly