一、前言
二、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】文件中更改程序的启动项；
========================================================================
如有问题，还请各位大佬多多指点~~~
每天进步一点点~加油鸭！
