.net 项目中配置 Swagger

一、前言

二、Swagger

三、.net 项目中添加Swagger

1、准备工作

（1）.net项目

（2）SwaggerController

（3）XML文档注释

2、安装Swagger包

3、添加配置swagger中间件

（1）添加Swagger构造器

（2）启用Swagger工具

（3）更改启动URL

（4）实现效果

四、自定义Swagger配置

1、添加文档信息

2、使用XML文档注释

3、【Program.cs】完整配置

一、前言

作为一名程序员，有两件事是令我本人很头疼的：

第一，是没有接口文档；
第二，是让我写接口文档；

那有没有一种方法，可以自动的生成开发文档呢？

那当然是有的，就我这个小菜菜能遇到的问题，早就是被各位大佬解决了的！！！

（感谢感谢感谢~~~~~~~~）

二、Swagger

Swagger 规范在2015年，重命名为 OpenAPI 规范。

OpenAPI Specification - Version 3.1.0 | Swagger

OpenAPI 规范 (中文版)

是一个开源的API设计工具和API文档生成工具；
可以帮助开发人员更快、更简单的构建RESTful API；
可以自动生成交互式的API文档；
可以生成与API实时同步的接口文档；
可以在SwaggerUI中直接进行接口测试；
使得开发、测试、部署API都更加的容易便捷；

三、.net 项目中添加Swagger

1、准备工作

（1）.net项目

如果在已有项目中添加Swagger的相关配置，那就一步步添加即可；

没有的话，可以新建一个.net项目，来学习研究Swagger这个伟大的工具；

打开Visual Studio，创建一个新的测试项目【Zyl_Swagger_Demo】；
选择【.net 8.0】；
选择【启用OpenApi支持】；

刚创建好的项目启动后，会自动在浏览器中打开Swagger页面，如下图所示；

注意：

如果项目跑起来后，没有显示如图所示界面，可能是因为在创建的时候，并未选择【启用OpenApi支持】的选项；
新建项目时勾选了【启用OpenApi支持】的，项目中会自动安装Swagger包，并添加配置Swagger中间件；
第2步（安装Swagger包）和第3步（添加配置swagger中间件）就可以省略不看了；

（2）SwaggerController

新建一个测试用的SwaggerController控制器；

【SwaggerController.cs】

using Microsoft.AspNetCore.Mvc;namespace Zyl_Swagger_Demo.Controllers
{[Route("api/[controller]/[action]")][ApiController]public class SwaggerController : ControllerBase{/// <summary>/// 两个数的四则运算/// </summary>/// <param name="a">数字a</param>/// <param name="b">数字b</param>/// <param name="type">运算符号</param>/// <remarks>/// 运算符号只能是 +、-、*、\ 中的一种/// </remarks>/// <response code="200">接口数据正常返回</response>/// <response code="400">参数传递有误</response>[HttpPost]public string Calculate(int a, int b, string type) { switch (type.Trim()) {case "+":return $"两数相加得：{a + b}";case "-":return $"两数相减得：{a + b}";case "*":return $"两数相乘得：{a + b}";case "/":return $"两数相除得：{a + b}";default:return "您输入的类型有误，请重新输入！";}}}
}

注意：在这个Controller 中已经添加了一些XML文档注释；

（3）XML文档注释

Documentation comments - C# （文档注释）

<summary> 用来描述接口具体功能；
<param> 用来描述接口参数；
<remarks> 用来描述接口补充信息；
<response> 用来描述接口响应内容；
......

Tag	Purpose
`<c>`	Set text in a code-like font
`<code>`	Set one or more lines of source code or program output
`<example>`	Indicate an example
`<exception>`	Identifies the exceptions a method can throw
`<include>`	Includes XML from an external file
`<list>`	Create a list or table
`<para>`	Permit structure to be added to text
`<param>`	Describe a parameter for a method or constructor
`<paramref>`	Identify that a word is a parameter name
`<permission>`	Document the security accessibility of a member
`<remarks>`	Describe additional information about a type
`<returns>`	Describe the return value of a method
`<see>`	Specify a link
`<seealso>`	Generate a See Also entry
`<summary>`	Describe a type or a member of a type
`<typeparam>`	Describe a type parameter for a generic type or method
`<typeparamref>`	Identify that a word is a type parameter name
`<value>`	Describe a property

2、安装Swagger包

使用NuGet安装【Swashbuckle.AspNetCore】包；

3、添加配置swagger中间件

（1）添加Swagger构造器

添加Swagger中间件到项目中；

【Program.cs】

......builder.Services.AddControllers();// 添加Swagger构造器
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();......

（2）启用Swagger工具

在开发环境中启用Swagger中间件和SwaggerUI工具；

【Program.cs】

......if (app.Environment.IsDevelopment())
{app.UseSwagger();   // 启用Swagger中间件app.UseSwaggerUI(); // 启用SwaggerUI工具
}......

（3）更改启动URL

更改项目启动时的URL，启动时打开SwaggerUI页面；

【launchSettings.json】

......"launchBrowser": true,
"launchUrl": "swagger",......

（4）实现效果

出现如下图所示SwaggerUI界面，则说明Swagger工具添加成功；

emmmm......

一个开发文档如果长成这样，那看到的人员估计是要疯掉的；

虽然现在还没有我们想要的一些接口信息，但可以通过Swagger配置，添加一些扩展内容；

四、自定义Swagger配置

1、添加文档信息

// 添加Swagger构造器
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{options.SwaggerDoc("v1", new OpenApiInfo{Version = "V1", // 接口文档版本Title = "Swagger API",  // 接口文档标题Description = "这是用来测试Swagger的接口文档！",    // 接口文档描述});
});

2、使用XML文档注释

在【Program.cs】中，添加XML文档注释；

......builder.Services.AddSwaggerGen(options =>
{options.SwaggerDoc("v1", new OpenApiInfo{Version = "V1", // 接口文档版本Title = "Swagger API",  // 接口文档标题Description = "这是用来测试Swagger的接口文档！",    // 接口文档描述});// 添加XML注释var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);options.IncludeXmlComments(xmlFilePath);
});......

重新启动，就可以看到在SwapperController接口中添加的XML文档注释相关信息了。

3、【Program.cs】完整配置

【Program.cs】

using System.Reflection;
using Microsoft.OpenApi.Models;namespace Zyl_Swagger_Demo
{public class Program{public static void Main(string[] args){var builder = WebApplication.CreateBuilder(args);// Add services to the container.builder.Services.AddControllers();// 添加Swagger构造器builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(options =>{options.SwaggerDoc("v1", new OpenApiInfo{Version = "V1", // 接口文档版本Title = "Swagger API",  // 接口文档标题Description = "这是用来测试Swagger的接口文档！",    // 接口文档描述});// 添加XML注释var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);options.IncludeXmlComments(xmlFilePath);});var app = builder.Build();// Configure the HTTP request pipeline.if (app.Environment.IsDevelopment()){// 启用Swagger中间件app.UseSwagger();// 启用SwaggerUI工具app.UseSwaggerUI(); }app.UseHttpsRedirection();app.UseAuthorization();app.MapControllers();app.Run();}}
}

注意：一定要在【launchSettings.json】文件中更改程序的启动项；