DotNetGuideAPI文档：使用Swagger自动生成接口文档

DotNetGuideAPI文档：使用Swagger自动生成接口文档

【免费下载链接】DotNetGuide 🐱‍🚀【C#/.NET/.NET Core学习、工作、面试指南】记录、收集和总结C#/.NET/.NET Core基础知识、学习路线、开发实战、学习视频、文章、书籍、项目框架、社区组织、开发必备工具、常见面试题、面试须知、简历模板、以及自己在学习和工作中的一些微薄见解。希望能和大家一起学习，共同进步👊【让现在的自己不再迷茫✨，如果本知识库能为您提供帮助，别忘了给予支持哦(关注、点赞、分享)💖】。 项目地址: https://gitcode.com/GitHub_Trending/do/DotNetGuide

引言：告别手写文档的痛苦

你是否还在为维护API文档而烦恼？手动编写接口文档不仅耗时耗力，还容易出现更新不及时、格式不统一等问题。本文将详细介绍如何在DotNetGuide项目中集成Swagger（OpenAPI），实现接口文档的自动生成、实时更新和交互式测试，让开发者专注于代码逻辑而非文档编写。

读完本文后，你将能够：

• 理解Swagger在.NET生态中的核心价值
• 掌握在ASP.NET Core项目中配置Swagger的完整流程
• 自定义接口文档的显示信息和安全设置
• 实现接口版本控制与文档分组
• 解决Swagger在生产环境中的部署问题

一、Swagger/OpenAPI简介

1.1 核心概念

术语	定义	作用
OpenAPI	一种规范，定义RESTful API的描述格式	统一API文档标准，支持跨语言、跨平台
Swagger	OpenAPI规范的实现工具集	提供文档生成、接口测试、客户端SDK生成等功能
Swashbuckle	.NET平台的Swagger实现	将Swagger集成到ASP.NET Core项目中

1.2 为什么选择Swagger

二、环境准备与项目配置

2.1 创建ASP.NET Core Web API项目

dotnet new webapi -n DotNetGuide.Api
cd DotNetGuide.Api

2.2 添加Swagger依赖

dotnet add package Swashbuckle.AspNetCore --version 6.5.0

2.3 基础配置（Program.cs）

var builder = WebApplication.CreateBuilder(args);

// 添加Swagger服务
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "DotNetGuide API",
        Description = "基于ASP.NET Core的RESTful API文档",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "DotNetGuide团队",
            Email = "contact@dotnetguide.com"
        },
        License = new OpenApiLicense
        {
            Name = "MIT License",
            Url = new Uri("https://opensource.org/licenses/MIT")
        }
    });
});

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

var app = builder.Build();

// 开发环境启用Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "DotNetGuide API v1");
        options.DocumentTitle = "DotNetGuide API文档";
        options.DefaultModelsExpandDepth(-1); // 隐藏Schemas
    });
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

三、高级配置与自定义

3.1 接口注释生成

1. 在项目文件(.csproj)中添加：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

2. 在Swagger配置中启用注释：

builder.Services.AddSwaggerGen(options =>
{
    // ...其他配置
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

3.2 接口版本控制

// 添加版本控制服务
builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// 配置多版本Swagger
builder.Services.AddSwaggerGen(options =>
{
    var versions = new[] { "v1", "v2" };
    foreach (var version in versions)
    {
        options.SwaggerDoc(version, new OpenApiInfo 
        { 
            Title = $"DotNetGuide API {version}", 
            Version = version 
        });
    }
    
    // 根据路由中的版本参数选择文档
    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        apiDesc.TryGetMethodInfo(out var methodInfo);
        var versions = methodInfo?.DeclaringType?.GetCustomAttributes<ApiVersionAttribute>()?.SelectMany(a => a.Versions);
        return versions?.Any(v => docName == $"v{v.MajorVersion}") ?? false;
    });
});

3.3 安全配置（JWT认证）

builder.Services.AddSwaggerGen(options =>
{
    // ...其他配置
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "请输入JWT令牌",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "bearer"
    });
    
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] { }
        }
    });
});

四、控制器示例与文档展示

4.1 创建示例控制器

/// <summary>
/// 用户管理接口
/// </summary>
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// 获取用户列表
    /// </summary>
    /// <param name="page">页码</param>
    /// <param name="size">每页条数</param>
    /// <returns>用户列表</returns>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public ActionResult<IEnumerable<UserDto>> GetUsers(
        [FromQuery, Required] int page, 
        [FromQuery, Required] int size)
    {
        // 实现代码...
        return Ok(new List<UserDto>());
    }

    /// <summary>
    /// 获取用户详情
    /// </summary>
    /// <param name="id">用户ID</param>
    /// <returns>用户详情</returns>
    [HttpGet("{id}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ActionResult<UserDto> GetUser(int id)
    {
        // 实现代码...
        return Ok(new UserDto());
    }
}

/// <summary>
/// 用户数据传输对象
/// </summary>
public class UserDto
{
    /// <summary>
    /// 用户ID
    /// </summary>
    public int Id { get; set; }
    
    /// <summary>
    /// 用户名
    /// </summary>
    public string Name { get; set; }
    
    /// <summary>
    /// 邮箱地址
    /// </summary>
    public string Email { get; set; }
}

4.2 Swagger UI界面功能

五、生产环境配置与部署

5.1 环境隔离配置

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "DotNetGuide API v1");
        options.SwaggerEndpoint("/swagger/v2/swagger.json", "DotNetGuide API v2");
    });
}
else
{
    // 生产环境仅启用Swagger文档JSON，不提供UI
    app.UseSwagger(options =>
    {
        options.RouteTemplate = "docs/{documentName}/swagger.json";
    });
}

5.2 性能优化

优化项	实现方式	效果
禁用Schema展开	DefaultModelsExpandDepth(-1)	减少初始加载时间30%+
文档压缩	UseResponseCompression()	减少传输数据量60%+
缓存控制	配置静态文件缓存策略	降低服务器请求压力

六、常见问题与解决方案

6.1 中文乱码问题

// 在Program.cs中配置
app.UseSwaggerUI(options =>
{
    options.InjectStylesheet("/swagger-ui/custom.css");
});

// wwwroot/swagger-ui/custom.css
body {
    font-family: "Microsoft YaHei", sans-serif;
}

6.2 复杂类型显示问题

使用[JsonPropertyName]特性重命名属性，使用[XmlArray]和[XmlArrayItem]特性优化集合显示。

七、总结与展望

Swagger作为API文档自动生成工具，极大地提升了开发效率和文档质量。通过本文介绍的配置方法，你可以在DotNetGuide项目中快速集成Swagger，并根据实际需求进行定制化开发。

未来，Swagger将在以下方面发挥更大作用：

• 与API测试工具深度集成
• 生成多语言客户端SDK
• 与CI/CD流程结合实现自动化文档部署
• 支持GraphQL等新型API规范

如果你觉得本文对你有帮助，请点赞、收藏并关注DotNetGuide项目，我们将持续分享更多.NET开发实践经验！

附录：常用Swagger配置参考

配置项	用途	示例值
SwaggerDoc	定义文档版本和基本信息	"v1", new OpenApiInfo { Title = "API", Version = "v1" }
IncludeXmlComments	包含XML注释文件	Path.Combine(AppContext.BaseDirectory, "Api.xml")
OperationFilter	自定义操作描述	new AddResponseHeadersFilter()
SchemaFilter	自定义模型描述	new EnumSchemaFilter()
DocInclusionPredicate	控制接口包含规则	(docName, apiDesc) => true

【免费下载链接】DotNetGuide 🐱‍🚀【C#/.NET/.NET Core学习、工作、面试指南】记录、收集和总结C#/.NET/.NET Core基础知识、学习路线、开发实战、学习视频、文章、书籍、项目框架、社区组织、开发必备工具、常见面试题、面试须知、简历模板、以及自己在学习和工作中的一些微薄见解。希望能和大家一起学习，共同进步👊【让现在的自己不再迷茫✨，如果本知识库能为您提供帮助，别忘了给予支持哦(关注、点赞、分享)💖】。 项目地址: https://gitcode.com/GitHub_Trending/do/DotNetGuide