.net 项目中配置 Swagger

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】

cs 复制代码

......

builder.Services.AddControllers();

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

......

（2）启用Swagger工具

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

【Program.cs】

cs 复制代码

......

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

......

（3）更改启动URL

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

【launchSettings.json】

cs 复制代码

......

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

......

（4）实现效果

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

emmmm......

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

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

四、自定义Swagger配置

1、添加文档信息

cs 复制代码

// 添加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文档注释；

cs 复制代码

......

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】

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】文件中更改程序的启动项++；

========================================================================

如有问题，还请各位大佬多多指点~~~

每天进步一点点~加油鸭！

.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】完整配置

3、添加配置swagger中间件