使用swagger在netcorewebapi项目中自动生成文档

一、背景

随着前后端分离模式大行其道，我们需要将后端接口撰写成文档提供给前端，前端可以查看我们的接口，并测试，提高我们的开发效率，减少无效的沟通。在此情况下，通过代码自动生成文档，这种需求应运而生，swagger可以通过我们的代码和注释自动生成相关api接口文档，并且可以在线查看，实时更新，轻松测试，解决了我们的实际问题。

二、创建Webapi项目，并添加swagger引用

2.1 使用vs创建一个netcore2.2的webapi项目

项目创建成功，Controllers文件夹中即为我们的api接口

2.2 添加swagger包引用

通过nuget添加swagger包，需要引用两个包，包名称为

Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Annotations

三、创建接口并验证生成的api文档

3.1 在项目的Startup.cs文件中添加引用using Swashbuckle.AspNetCore.Swagger;

3.2 在ConfigureServices方法中添加如下代码

      services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info() { Title = "Api", Version = "V1" });
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                options.IncludeXmlComments(xmlPath);
            });

3.3 在Configure方法中添加启用方法

  app.UseSwagger()
                .UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                });

3.4 生成XML文件，并验证

验证自动生成的文档

我们的接口文档已经自动生成，且可测试

3.5 编写Controller并验证

创建控制器PersonController，继承自Controller，代码如下

   [ApiController]
    public class PersonController : Controller
    {
        /// <summary>
        /// 获取人员信息
        /// </summary>
        /// 
        /// <returns></returns>
        [HttpGet]
        [Route("api/Person/Index")]
        public List<Person> Index()
        {
            return new List<Person>()
            {
                new Person() {Age = 10, Name = "张三"},
                new Person() {Age = 20, Name = "李四"},
            };
        }
   }

此时再打开swagger文档并查看

可以看到我们的注释也在文档中显示了。

四、小结

swagger是一个非常强大的插件，可以帮助我们快速生成api文档，给前后端分离带来了极大的方便。
参考文档：
1.https://github.com/domaindrivendev/Swashbuckle.AspNetCore
2.https://www.cnblogs.com/viter/p/10053660.html
3.https://www.cnblogs.com/yilezhu/p/9241261.html