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

一、背景

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

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

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

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

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

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

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

2.2 添加swagger包引用

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

Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Annotations

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

三、创建接口并验证生成的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文件,并验证

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

验证自动生成的文档

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

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

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在netcorewebapi项目中自动生成文档

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

四、小结

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

上一篇:JS中事件绑定问题


下一篇:算法笔记_069:Floyd算法简单介绍(Java)