.NET Framework 4.8下NSwag.MSBuild生成OpenAPI规范的装饰方法咨询

核心方案：自定义IDocumentProcessor并在nswag.json中配置 #

NSwag.MSBuild不会自动读取项目中硬编码的后处理逻辑，必须通过配置文件显式指定自定义文档处理器来装饰生成的OpenAPI规范。以下是具体实现步骤：

1. 实现自定义DocumentProcessor #

在你的.NET Framework 4.8项目中创建一个类，实现NSwag.Generation.Processors.IDocumentProcessor接口，在其中编写修改OpenAPI文档的逻辑（标题、版本、描述、扩展等）：

using NSwag.Generation.Processors;
using NSwag.Generation.Processors.Contexts;
using System.Threading.Tasks;

public class CustomOpenApiDocumentProcessor : IDocumentProcessor
{
    public Task ProcessAsync(DocumentProcessorContext context)
    {
        // 修改基础文档信息
        context.Document.Info.Title = "你的API标题";
        context.Document.Info.Version = "v2.0";
        context.Document.Info.Description = "API详细描述内容";

        // 添加自定义扩展
        context.Document.Extensions.Add("x-custom-extension", "自定义扩展值");
        context.Document.Info.Extensions.Add("x-info-extension", new { Author = "开发团队", Email = "dev@example.com" });

        // 确保输出OpenAPI v3规范
        context.Document.OpenApiVersion = "3.0.0";

        return Task.CompletedTask;
    }
}

2. 生成/配置nswag.json文件 #

你不需要依赖NSwag Studio，手动创建或通过NSwag CLI生成基础配置后修改即可：

• 打开命令行，进入项目根目录，执行以下命令生成WebAPI基础配置：

  nswag new webapi
  

• 打开生成的nswag.json，找到documentProcessors节点，添加自定义处理器的配置：

  {
    "runtime": "Net48",
    "defaultVariables": null,
    "documentGenerator": {
      "webApiToOpenApi": {
        "assemblyPaths": [
          "bin/Debug/你的项目程序集.dll"
        ],
        "assemblyConfig": "Web.config",
        "documentProcessors": [
          {
            "type": "你的命名空间.CustomOpenApiDocumentProcessor, 你的项目程序集名称"
          }
        ],
        "openapiVersion": "3.0.0",
        // 保留其他默认配置...
      }
    },
    "output": "openapi.json"
  }
  

  注意替换你的命名空间、你的项目程序集名称为实际值，确保assemblyPaths指向编译后的程序集路径。

3. 配置MSBuild任务 #

确保你的项目文件（.csproj）中的NSwag.MSBuild任务引用这个nswag.json：

<Project>
  <!-- 其他项目配置 -->
  <Target Name="NSwag" AfterTargets="Build">
    <Exec Command="$(NSwagExe_Net48) run nswag.json /variables:Configuration=$(Configuration)" />
  </Target>
</Project>

4. 验证效果 #

编译项目后，NSwag.MSBuild会执行nswag.json中的配置，调用自定义处理器修改OpenAPI规范，生成的openapi.json会包含你设置的标题、版本、描述和扩展。

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