.net swagger生成接口文档

Swagger 是一个用于设计、构建、记录和使用 RESTful Web 服务的框架。它通过 Swagger 规范（OpenAPI 规范）来描述 API，并提供了一系列工具来生成、展示和维护这些 API 文档。

基础概念

Swagger/OpenAPI:

OpenAPI 规范: 一种描述 RESTful API 的标准格式。
Swagger UI: 一个将 OpenAPI 规范文件转换为交互式 API 文档的工具。
Swagger Editor: 一个在线编辑器，用于编写和验证 OpenAPI 规范文件。

优势

自动生成文档: 开发者只需编写一次 API 描述，Swagger 可以自动生成文档。
交互式体验: 用户可以直接在浏览器中测试 API 端点。
标准化: 使用 OpenAPI 规范，确保 API 描述的一致性和可读性。
集成方便: 可以轻松集成到现有的 .NET 项目中。

类型

Swagger/OpenAPI 2.0: 较早的版本，广泛使用。
OpenAPI 3.0: 最新版本，提供了更多功能和更好的支持。

应用场景

API 设计与开发: 在设计和开发阶段，实时查看和测试 API。
文档维护: 自动化文档更新，减少手动维护的工作量。
团队协作: 方便团队成员之间的沟通和协作。
客户端生成: 使用 Swagger Codegen 自动生成客户端库。

在 .NET 中集成 Swagger

以下是一个简单的示例，展示如何在 ASP.NET Core 项目中集成 Swagger：

安装 NuGet 包

首先，安装必要的 NuGet 包：

dotnet add package Swashbuckle.AspNetCore

配置 Swagger

在 Startup.cs 文件中进行配置：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        // 添加 Swagger 生成器
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

            // 如果有 XML 注释，可以启用它们
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();

            // 启用 Swagger UI
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

控制器示例

创建一个简单的控制器，并添加一些 API 操作：

[ApiController]
[Route("[controller]")]
public class SampleController : ControllerBase
{
    [HttpGet]
    public ActionResult<string> Get()
    {
        return "Hello, World!";
    }

    [HttpPost]
    public ActionResult<string> Post([FromBody] string value)
    {
        return $"Received: {value}";
    }
}