.net swagger 显示注释

.NET Swagger 显示注释

Swagger 是一种用于描述和可视化 RESTful API 的工具。它提供了一种简单的方式来展示 API 的所有细节，包括每个端点的请求和响应参数、请求方法以及其他元数据。在 .NET 开发中，我们可以使用 Swagger 来生成文档和客户端代码，并通过添加注释来增强其可读性。

什么是 Swagger 注释？

Swagger 注释是 C# 代码中的特殊注释，用于描述 API 端点、请求和响应模型以及其他元数据。这些注释会被 Swagger 扫描器解析，然后生成 Swagger 规范文档。通过在代码中添加这些注释，我们可以方便地将代码和文档统一在一起，减少了维护文档的工作量。

如何在 .NET 中使用 Swagger 注释？

首先，我们需要在项目中安装 Swagger 相关的 NuGet 包。可以通过 NuGet 包管理器或使用以下命令行来完成安装：

dotnet add package Swashbuckle.AspNetCore

接下来，在 Startup.cs 文件中启用 Swagger 并配置注释生成选项。我们需要添加以下代码：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public void ConfigureServices(IServiceCollection services)
{
    // ...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        // 配置注释生成选项
        c.DocumentFilter<SwaggerDocumentFilter>();
    });

    // ...
}

public class SwaggerDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var assembly = Assembly.GetExecutingAssembly();
        var types = assembly.GetTypes();
        foreach (var type in types)
        {
            if (type.GetCustomAttributes().Any(a => a is SwaggerTagAttribute))
            {
                var routes = type.GetMethods()
                    .Where(m => m.GetCustomAttributes().Any(a => a is SwaggerOperationAttribute))
                    .Select(m => m.GetCustomAttributes<SwaggerOperationAttribute>().First().Tags.First())
                    .Distinct();
                
                foreach (var route in routes)
                {
                    var routeDoc = new OpenApiTag
                    {
                        Name = route,
                        Description = type.GetCustomAttribute<SwaggerTagAttribute>()?.Description
                    };
                    if (!swaggerDoc.Tags.Contains(routeDoc))
                    {
                        swaggerDoc.Tags.Add(routeDoc);
                    }
                }
            }
        }
    }
}

上述代码会根据代码中的 SwaggerTagAttribute 和 SwaggerOperationAttribute 来生成 Swagger 文档的标签和描述。

接下来，我们可以在控制器的方法上使用 Swagger 注释。以下是一些常用的注释标记：

• SwaggerTagAttribute：用于标记控制器类，并为其指定描述。
• SwaggerOperationAttribute：用于标记控制器方法，并为其指定描述。
• ProducesResponseTypeAttribute：用于指定方法的响应类型。

下面是一个简单的控制器示例：

[ApiController]
[SwaggerTag("示例控制器", "这是一个示例控制器")]
public class SampleController : ControllerBase
{
    [HttpGet("api/sample/{id}")]
    [SwaggerOperation("通过 ID 获取示例", "根据 ID 获取示例数据")]
    [ProducesResponseType(typeof(SampleModel), 200)]
    [ProducesResponseType(typeof(ErrorResponse), 400)]
    public ActionResult<SampleModel> GetById(int id)
    {
        if (id <= 0)
        {
            return BadRequest(new ErrorResponse { Message = "Invalid ID" });
        }

        // 根据 ID 从数据库获取样本数据
        var sample = _repository.GetById(id);

        if (sample == null)
        {
            return NotFound();
        }

        return Ok(sample);
    }
}

生成 Swagger 规范文档

当我们完成了控制器和注释的编写后，我们可以使用以下代码来生成 Swagger 规范文档：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

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

    // ...
}

上述代码将在 URL /swagger/v1/swagger.json 中生成 Swagger 规范文档，并使用 Swagger UI 来可视化显示 API。

结论

使用 Swagger 注释可以让我们方便地将代码和文档统一在一起，在