正文
使用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
