基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档

在随着微服务的普及，出现了太多的API服务，那么这些服务的接口文档维护的成本就变的非常高。所以就有了swagger这样的一个智能的自动管理接口文档工具。

先看下我的项目创建一个 Core API，如图：

第一步  在nuget里面需要添加引用 ：

 直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装 

如图：

第二步、添加服务

Startup里面先注册服务，然后添加中间件

在Startup类的ConfigureServices方法里面注入服务：

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
    });
    services.AddControllers();
}

第三步、添加中间件

在Startup类的Configure方法里面添加Swagger有关的中间件：

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

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

    app.UseRouting();

    app.UseAuthorization();

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

第四步： 添加控制器

新建一个控制器，里面包括基础的增删改查方法：

注意：core3.1里面添加控制器有4种不同的类型。

1:这里Controller的类时继承了 Controller类，但是API controller 继承的是ControllerBase类

2:在API controller跟controller里面又分  Empty跟写好的方法，区别就是一个controller里面是空的，一个里面是有增删改查的方法。

3:默认controller里面的    [Route("api/[controller]")]  是这样的。也就是到控制器，所以默认只能有get ，post， put会和 delete方法。所以需要手动路由到action。有2种方式：  在控制器上面改为 [Route("api/[controller]/[action]")]  或是 在action上面添加         [Route("方法名称")]

 

using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{
    [Route("api/student")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }

        [HttpPost]
        public void Post()
        {
            
        }

        [HttpPut]
        public void Put()
        {

        }

        [HttpDelete]
        public void Delete()
        {

        }
    }
}

 第五步 运行起来项目：

运行起来，看先 并不能主动启动swagger页面。这里需要配置一下：

先找到这个文件：launchsettings.json

再打开内容：把如图的两处修改一下，设置为空 或者 直接写swagger都可以

这个时候启动起来就会是首页为 swagger页面：如图：

第六步：注释显示

这里看到还有注释，其实根据上面的步骤是不会显示出注释的，

那么怎么添加注释呢？

第一步：在Startup类里面的ConfigureServices方法需要稍微添加几句代码

public void ConfigureServices(IServiceCollection services)
{
    #region 添加Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1",new  OpenApiInfo { Title = "My API", Version = "v1" });
        // 获取xml文件名
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        // 获取xml文件路径
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        // 添加控制器层注释，true表示显示控制器注释
        options.IncludeXmlComments(xmlPath, true);
    });
    #endregion
    services.AddControllers();

}
 

2：在控制器里面的方法 跟类名需要添加注释信息：例如:

/// <summary>
    /// 订单管理API
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class OrderController : ControllerBase
    {
        // GET: api/<OrderController>
        /// <summary>
        /// 查询所有信息
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/<OrderController>/5
        /// <summary>
        /// 查询单条信息
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

        // POST api/<OrderController>
        /// <summary>
        /// 新增方法
        /// </summary>
        /// <param name="value"></param>
        [HttpPost]
        public void Post([FromBody]string value)
        {

        }

}

注意一下：这里晚上说需要再在nuget里面去安装一个包 安装Microsoft.Extensions.PlatformAbstractions包：但是我没有安装，一样的可以把注释显示出来，一开始是安装了，但是发现安装之后没有任何用处，就卸载了，注释一样可以显示出来，不知道为什么很多人说要引用这个包。

3：项目右键，选择属性，勾选“XML文档文件”，如下图所示：

在运行程序：

可以看到，刚才在控制器上面添加的注释信息都显示出来了。这样前端就可以直接查看接口文档了。

Swagger除了可以显示接口注释以外，还可以进行调试，以前调试都是使用Postman，我们也可以直接使用Swagger进行调试。

启动项目后会发现：

这时候是不能输入的，只能查看，点击右上角的“Try it out”：

这时会变成Cancel，点击Cancel会回到Try it out:

 我们点击Execute执行：

 下面会列出执行结果：

 

这样就完成了GET方法的调试。这是无参数方法的调试，如果有参数的方法怎么调试呢？我们以POT方法为例。我们点开POST方法：

然后点击“Tty it out”，可以变成输入状态，输入参数，点击“Execute”按钮执行：

最后在下面就会输出结果：

PUT和DELETE可以使用同样的方式进行测试。

有人发现，本地的swagger有字段说明，但是发布到服务器上，就没有字段说明，原因是.netcore 3.1发布后，不会生成xml文件。解决方方法是，在vs2019项目里，刚刚我们设置成功生成的2个xml文件，右击-“属性”-“复制到输出目录”设置为“始终复制”即可。

 

总结：

上面简单介绍了什么是Swagger，以及如何利用Swagger进行调试，这样只需要启动程序即可，不需要在额外的使用Postman进行测试。使用Swagger可以保持接口文档能够及时更新。