自托管.NET Core API（常规路由）能否用NSwag生成OpenAPI规范？

好问题！我来帮你拆解这两个核心疑问：

NSwag确实支持为使用常规路由（而非特性路由）的.NET Core API生成OpenAPI规范，不过它的底层依赖是.NET Core自带的ApiExplorer组件来收集API的元数据信息——这也是你第二个问题的核心。

和Swashbuckle不同，NSwag在处理非特性路由的API时，只要正确配置ApiExplorer，就能识别并解析常规路由规则，进而生成对应的OpenAPI文档。

ApiExplorer是.NET Core框架的核心组件，所有基于它的文档生成工具（包括NSwag、Swashbuckle）都依赖它来获取API的路由、参数、响应等元数据。对于常规路由的API，你需要做以下几步配置：

1. 启用ApiExplorer
   在你的Program.cs（或Startup.cs）中，确保在添加控制器服务时启用ApiExplorer：

   builder.Services.AddControllers()
       .AddApiExplorer(); // 启用ApiExplorer
   

2. 为常规路由的API添加ApiExplorer标记
   因为常规路由没有特性路由那样明确的元数据标记，你需要给控制器或Action添加[ApiExplorerSettings]特性，帮助ApiExplorer识别这些API并归类：

   [ApiController]
   [ApiExplorerSettings(GroupName = "v1", DisplayName = "常规路由API")]
   public class LegacyController : ControllerBase
   {
       // 常规路由匹配的Action
       public IActionResult GetData(int id)
       {
           return Ok(new { Id = id, Data = "Sample" });
       }
   }
   

3. 配置并启用NSwag
   接下来配置NSwag，让它基于ApiExplorer的数据生成OpenAPI文档：

   // 添加NSwag文档服务
   builder.Services.AddOpenApiDocument(settings =>
   {
       settings.Title = "我的常规路由API";
       settings.Version = "v1";
       // 确保NSwag扫描所有ApiExplorer识别的API
       settings.DocumentName = "v1";
   });
   
   // 在中间件中启用NSwag的Swagger UI和OpenAPI端点
   app.UseOpenApi();
   app.UseSwaggerUi();
   

虽然NSwag支持常规路由的API文档生成，但特性路由的元数据更明确，生成的OpenAPI规范会更清晰、更符合RESTful规范。如果你的API有迭代计划，建议逐步迁移到特性路由；如果必须保留常规路由，上述配置就能满足需求。

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