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

什么是Swagger？

如下引用swagger官方的解释

翻译过来就是

当然，这些了解一下就好了，对我们来说并没有什么用，只需要知道他是一个简便的接口调试方式即可，接下来我们使用一下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);

6. swagger展示

到这里我们就完成配置了，接下来我们运行项目看一下效果。

这里访问的话是我默认的地址：https://localhost:44383/weatherforecast，我们需要把后面的weatherforecast更换为swagger/index.html，如下

访问地址：http://localhost:54848/swagger/index.html

很显然我们swagger搭建成功了，接下来我们访问看看效果怎么样。

7. swagger如何调试接口

我们可以看到我们的所有接口，然后找到需要调试的接口调试就可以了，我们调试一下带参数的。

1、点击需要调试的接口地址；

2、点击Try it out，这时会变成Cancel，点击Cancel会回到Try it out（Cancel状态是可以读写状态，Try it out是只读状态）；

3、在输入框输入内容后，点击Execute进行接口请求。

4、点击请求后，Server response位置就是接口返回的的数据了。

 

这样我们就完成了swagger的简单操作啦。

总结

对于swagger的应用远远不止于此，但是常规的操作已经够我们日常开发中使用了，具体问题具体分析，需要拓展时在进行添加即可。

其实不管是使用Fiddler、PostMan、JMeter、SoupUI等 还是swagger，我们不用盲目跟风，选择自己用起来最熟练的使用即可。

工具嘛，选择一个自己能熟练使用就挺好了，当然，能了解更多也没坏处。

喜欢就点赞加关注。