如何为NopCommerce 4.5 API插件添加Swagger文档？

当然可以给NopCommerce 4.5的API插件添加Swagger文档，以下是具体的实现步骤：

1. 安装Swagger相关NuGet包 #

在你的API插件项目中，通过NuGet包管理器安装以下包：

• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerGen
• Swashbuckle.AspNetCore.SwaggerUI

2. 配置Swagger服务 #

如果插件还没有Startup类，新建一个继承自INopStartup的类并添加[NopStartup]特性，在类中配置Swagger服务：

using Microsoft.OpenApi.Models;
using System.Reflection;
using System.IO;
using Nop.Core.Infrastructure;

[NopStartup]
public class SwaggerStartup : INopStartup
{
    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddSwaggerGen(c =>
        {
            // 定义Swagger文档的基础信息
            c.SwaggerDoc("v1", new OpenApiInfo 
            { 
                Title = "你的API插件名称", 
                Version = "v1",
                Description = "NopCommerce插件API文档"
            });

            // 可选：加载XML注释（需先启用项目的XML文档生成）
            var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
            c.IncludeXmlComments(xmlFilePath);
        });
    }

    public void Configure(IApplicationBuilder application)
    {
        // 启用Swagger JSON数据端点
        application.UseSwagger();

        // 启用Swagger UI可视化界面
        application.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API插件名称 v1");
            // 可选：设置Swagger UI直接通过站点根路径访问（去掉/swagger前缀）
            // c.RoutePrefix = string.Empty;
        });
    }

    // 设置启动顺序，确保在其他API配置后加载
    public int Order => 100;
}

3. 启用XML注释（可选但推荐） #

右键API插件项目 → 属性 → 生成 → 勾选“XML文档文件”，保留默认路径即可。之后在API控制器和方法上添加的///格式注释，会自动同步到Swagger文档中。

4. 配置身份验证支持（若API需授权） #

如果你的API使用JWT或其他身份验证机制，在AddSwaggerGen中添加安全配置，让Swagger支持令牌输入：

services.AddSwaggerGen(c =>
{
    // ... 保留之前的配置

    // 定义JWT身份验证规则
    var securityScheme = new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "请输入格式为 `Bearer {你的令牌}` 的授权头"
    };
    c.AddSecurityDefinition("Bearer", securityScheme);

    // 配置所有API接口需要身份验证
    var securityReq = new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
            },
            new string[] {}
        }
    };
    c.AddSecurityRequirement(securityReq);
});

5. 测试文档 #

启动NopCommerce项目后，访问http://你的站点域名/swagger（如果设置了RoutePrefix = string.Empty则直接访问站点根路径），即可看到API插件的Swagger界面，可直接在界面上测试接口调用。

注意事项 #

• 确保插件的plugin.json配置正确，插件已被NopCommerce正常加载。
• 若多个API插件需要合并文档，可在AddSwaggerGen中添加多个SwaggerDoc，并在SwaggerUI中配置对应端点。

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