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

2022-11-04 15:28:01

一、背景

随着前后端分离模式大行其道，我们需要将后端接口撰写成文档提供给前端，前端可以查看我们的接口，并测试，提高我们的开发效率，减少无效的沟通。在此情况下，通过代码自动生成文档，这种需求应运而生，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

码农公寓