10分钟带你进入Swagger的世界，快来看一看吧

时间：03-14来源：作者：点击数：

什么是Swagger？

如下引用swagger官方的解释

Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Swagger consists of a mix of open source, free and commercially available tools that allow anyone, from technical engineers to street smart product managers to build amazing APIs that everyone loves.

Swagger is built by SmartBear Software, the leader in software quality tools for teams. SmartBear is behind some of the biggest names in the software space, including Swagger, SoapUI and QAComplete.

翻译过来就是

Swagger 是一套功能强大且易于使用的 API 开发人员工具组件，适用于团队和个人，支持从设计文档到测试部署的整个 API 生命周期的开发。

Swagger 由多种开源、免费和商业可用的工具组成，允许任何人（从技术工程师到智能产品经理）构建每个人都喜欢且令人惊叹的 API。

Swagger 由 SmartBear Software 构建，SmartBear Software 是团队软件质量工具的领导者。SmartBear 支持软件领域的一些大腕，包括 Swagger、SoapUI 和 QAComplete。

当然，这些了解一下就好了，对我们来说并没有什么用，只需要知道他是一个简便的接口调试方式即可，接下来我们使用一下swagger。

在NET Core API中使用swagger

1. 创建net core api项目

这里使用ASP.NET Core 3.1创建WebAPI接口项目，命名为swaggerDemo，创建如下

创建完成后的项目结构

2. 引入swagger中间件

在nuget里面引入swagger中间件，名称为Swashbuckle.AspNetCore

3. 配置swagger中间件

在Startup.cs文件的ConfigureServices方法中添加如下代码，注意下面的 AddSwaggerGen 方法是用于给 API 文档添加一些元数据。

PS：注意，这里提前说一下，如果没有写xml文件解析，那么最后的文档是没有方法的注释和方法参数的注释，注意参考下面的第5点。

public void ConfigureServices(IServiceCollection services)
        {
            // 添加Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "我是当前API的名称",                     //swagger接口文档：名称
                    Version = "v1",                         //swagger接口文档：版本号
                    Description = "测试Swagger的使用方法"   //swagger接口文档：描述
                });

                //显示每个方法的注释和方法参数的注释
                // 获取xml文件名
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                // 获取xml文件路径
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 添加控制器层注释，true表示显示控制器注释
                c.IncludeXmlComments(xmlPath, true);
            });

            services.AddControllers();
        }

添加好中间件后，在Startup.cs文件的Configure方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务，如下：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            // begin 添加Swagger有关中间件
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");   
            });
            // end 添加Swagger有关中间件

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

4. 创建一个api接口控制器

创建一个Home接口的控制器，在Home控制器里面写入几个方法用于测试，如下完整显示，大家测试的时候用一个就可以了。

注意：这里route路由可以配置，也可以使用默认的。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;

namespace swaggerDemo.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class HomeController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
       {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };
        /// <summary>
        /// 不带任何参数的Get操作方法
        /// </summary>
        /// <remarks>
        /// 我是不带任何参数的Get操作方法
        /// </remarks>
        /// <returns></returns>
        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
        /// <summary>
        /// 带参数的get操作方法
        /// </summary>
        /// <remarks>
        /// 我是一个带参数的get操作方法
        /// </remarks>
        /// <param name="str">这是输入的字段</param>
        /// <returns></returns>
        [HttpGet("{str}")]
        public ActionResult<string> Get(string str)
        {
            return str;
        }
        /// <summary>
        /// 添加数据的操作方法
        /// </summary>
        /// <remarks>
        /// 我是添加功能
        /// </remarks>
        /// <param name="value">这是输入的字段</param>
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }
        /// <summary>
        /// （提交文件）修改数据的操作方法
        /// </summary>
        /// <remarks>
        /// 我是修改功能
        /// </remarks>
        /// <param name="file">文件名称</param>
        /// <param name="id">主键</param>
        [HttpPut("{id}")]
        public void Put(IFormFile file, int id)
        {

        }
        /// <summary>
        /// 删除数据的操作方法
        /// </summary>
        /// <remarks>
        /// 我是删除功能
        /// </remarks>
        /// <param name="id">主键</param>
        [HttpDelete("{id}")]
        public void Delete(int id)
        {

        }
    }
}

5. 设置显示注释

到这里我们的Swagger api文档是没有注释的，我们添加一下显示注释的操作。

点击 swaggerDemo 右键-》属性，点击生成，把xml文档文件勾选，勾选后会自动填充数据，里面的数据暂时不要动，如下。

然后在Startup.cs文件ConfigureServices方法的中间件services.AddSwaggerGen下面添加如下语句，上面如果添加过了的可以忽略。

//显示每个方法的注释和方法参数的注释
                // 获取xml文件名
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                // 获取xml文件路径
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 添加控制器层注释，true表示显示控制器注释
                c.IncludeXmlComments(xmlPath, true);