一、问题背景
随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了API接口,但是目前项目中对于API的管理很多时候还是通过手工编写文档,每次的需求变更只要涉及到接口的变更,文档都需要进行额外的维护,如果有哪个小伙伴忘记维护,很多时候就会造成一连续的问题,那如何可以更方便的解决API的沟通问题?Swagger给我们提供了一个方式,由于目前主要我是投入在.NET Core项目的开发中,所以以.NET Core作为示例
二、什么是Swagger
Swagger可以从不同的代码中,根据注释生成API信息,swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生成的文件生成API文档
三、.NET Core中使用
.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore,在startup.cs中加入如下代码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
// This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddSwaggerGen(c => { c.SwaggerDoc( "v1" , new Info { csharp" id="highlighter_699906">
接下来我们还需要在生成中勾上XML生成文档,如图所示
接下去我们可以运行起来了,调试,浏览器中输入http://localhost:50510/swagger/,这里端口啥的根据实际情况来,运行效果如下图所示:
可以看到swagger将方法上的注释以及实体的注释都抓出来了,并且显示在swaggerui,整体一目了然,并且可以通过try it按钮进行简单的调试,但是在具体项目中,可能存在需要将某些客户端信息通过header带到服务中,例如token信息,用户信息等(我们项目中就需要header中带上token传递到后端),那针对于这种情况要如何实现呢?可以看下面的做法
|