C#MVC项目引用Swagger的详细步骤

以下是基于ASP.NET Core项目集成Swagger的详细步骤（已适配当前项目结构）：

一、安装Swagger依赖包

1. 通过NuGet安装
   右键点击项目 → 管理NuGet程序包 → 搜索 Swashbuckle.AspNetCore → 安装最新稳定版

二、配置Swagger服务

2. 修改Program.cs

   var builder = WebApplication.CreateBuilder(args);
   
   // 添加Swagger服务配置
   builder.Services.AddSwaggerGen(c => {
       c.SwaggerDoc("v1", new OpenApiInfo {
           Version = "v1",
           Title = "图书管理API",
           Description = "包含分页查询等核心功能",
           Contact = new OpenApiContact { Name = "开发者", Email = "your@email.com" }
       });
       
       // 配置XML注释（需先启用项目属性中的XML生成）
       var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
       var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
       c.IncludeXmlComments(xmlPath, true);
   });
   
   // ...其他服务注册（如DbContext等）
   

3. 配置中间件
   在 var app = builder.Build(); 之后添加：

   app.UseSwagger();
   app.UseSwaggerUI(c => {
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "Book API v1");
       c.RoutePrefix = ""; // 将Swagger设为根路径访问
   });
   

三、启用XML注释

4. 修改项目文件
   右键项目 → 属性 → 生成 → 勾选 XML文档文件 → 路径保留默认值
   

   （或在 .csproj 中添加）：

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

5. 为BookController添加注释

   /// <summary>
   /// 获取分页图书数据
   /// </summary>
   /// <param name="pageNumber">页码（默认1）</param>
   /// <param name="pageSize">每页条目数（默认10）</param>
   /// <returns>包含分页元数据的图书列表</returns>
   [HttpGet("paged")]
   public async Task<ActionResult<PagedResult<Book>>> GetPagedBooks(...)
   

四、调整启动配置

6. 修改launchSettings.json
   将 profiles 中的 applicationUrl 统一为：

   "applicationUrl": "https://localhost:7044;http://localhost:5231"
   

   删除所有 launchUrl 属性，确保启动时直接加载Swagger UI

五、验证与访问

7. 运行项目
   按 F5 启动 → 浏览器会自动打开 https://localhost:7044 显示Swagger UI
   你将看到：
   • ✅ GET /Book/paged 分页接口
   • ✅ 参数说明（含默认值）
   • ✅ 模型结构展示（Book和PagedResult）

常见问题解决

• 404错误：检查 SwaggerEndpoint 路径是否与 SwaggerDoc 版本号匹配
• 注释不显示：确认XML文件生成路径与代码中的 xmlPath 一致
• 数据库连接失败：已配置的 TrustServerCertificate=True 可兼容本地SQL Server Express

通过以上配置，分页查询接口将获得完整的Swagger文档支持，前端开发者可直接在网页测试接口，无需Postman等工具。进阶功能（如JWT认证、版本控制）可参考OpenAPI规范扩展。