在随着微服务的普及,出现了太多的API服务,那么这些服务的接口文档维护的成本就变的非常高。所以就有了swagger这样的一个智能的自动管理接口文档工具。
先看下我的项目创建一个 Core API,如图:
直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装
Startup里面先注册服务,然后添加中间件
在Startup类的ConfigureServices方法里面注入服务:
public void ConfigureServices(IServiceCollection services)
{
// 添加Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
});
services.AddControllers();
}
在Startup类的Configure方法里面添加Swagger有关的中间件:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}// 添加Swagger有关中间件
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
});app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
新建一个控制器,里面包括基础的增删改查方法:
注意:core3.1里面添加控制器有4种不同的类型。
1:这里Controller的类时继承了 Controller类,但是API controller 继承的是ControllerBase类
2:在API controller跟controller里面又分 Empty跟写好的方法,区别就是一个controller里面是空的,一个里面是有增删改查的方法。
3:默认controller里面的 [Route("api/[controller]")] 是这样的。也就是到控制器,所以默认只能有get ,post, put会和 delete方法。所以需要手动路由到action。有2种方式: 在控制器上面改为 [Route("api/[controller]/[action]")] 或是 在action上面添加 [Route("方法名称")]
using Microsoft.AspNetCore.Mvc;
namespace SwaggerDemo.Controllers
{
[Route("api/student")]
[ApiController]
public class StudentController : ControllerBase
{
[HttpGet]
public string Get()
{
return "Tom";
}[HttpPost]
public void Post()
{
}[HttpPut]
public void Put()
{}
[HttpDelete]
public void Delete()
{}
}
}
运行起来,看先 并不能主动启动swagger页面。这里需要配置一下:
先找到这个文件:launchsettings.json
再打开内容:把如图的两处修改一下,设置为空 或者 直接写swagger都可以
这个时候启动起来就会是首页为 swagger页面:如图:
这里看到还有注释,其实根据上面的步骤是不会显示出注释的,
那么怎么添加注释呢?
第一步:在Startup类里面的ConfigureServices方法需要稍微添加几句代码
public void ConfigureServices(IServiceCollection services)
{
#region 添加Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1",new OpenApiInfo { Title = "My API", Version = "v1" });
// 获取xml文件名
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
// 获取xml文件路径
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 添加控制器层注释,true表示显示控制器注释
options.IncludeXmlComments(xmlPath, true);
});
#endregion
services.AddControllers();}
2:在控制器里面的方法 跟类名需要添加注释信息:例如:
///
/// 订单管理API
///
[Route("api/[controller]")]
[ApiController]
public class OrderController : ControllerBase
{
// GET: api/
///
/// 查询所有信息
///
///
[HttpGet]
public IEnumerableGet()
{
return new string[] { "value1", "value2" };
}// GET api/
/5
///
/// 查询单条信息
///
///
///
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}// POST api/
///
/// 新增方法
///
///
[HttpPost]
public void Post([FromBody]string value)
{}
}
注意一下:这里晚上说需要再在nuget里面去安装一个包 安装Microsoft.Extensions.PlatformAbstractions包:但是我没有安装,一样的可以把注释显示出来,一开始是安装了,但是发现安装之后没有任何用处,就卸载了,注释一样可以显示出来,不知道为什么很多人说要引用这个包。
3:项目右键,选择属性,勾选“XML文档文件”,如下图所示:
在运行程序:
可以看到,刚才在控制器上面添加的注释信息都显示出来了。这样前端就可以直接查看接口文档了。
Swagger除了可以显示接口注释以外,还可以进行调试,以前调试都是使用Postman,我们也可以直接使用Swagger进行调试。
启动项目后会发现:
这时候是不能输入的,只能查看,点击右上角的“Try it out”:
这时会变成Cancel,点击Cancel会回到Try it out:
我们点击Execute执行:
下面会列出执行结果:
这样就完成了GET方法的调试。这是无参数方法的调试,如果有参数的方法怎么调试呢?我们以POT方法为例。我们点开POST方法:
然后点击“Tty it out”,可以变成输入状态,输入参数,点击“Execute”按钮执行:
最后在下面就会输出结果:
PUT和DELETE可以使用同样的方式进行测试。
有人发现,本地的swagger有字段说明,但是发布到服务器上,就没有字段说明,原因是.netcore 3.1发布后,不会生成xml文件。解决方方法是,在vs2019项目里,刚刚我们设置成功生成的2个xml文件,右击-“属性”-“复制到输出目录”设置为“始终复制”即可。
上面简单介绍了什么是Swagger,以及如何利用Swagger进行调试,这样只需要启动程序即可,不需要在额外的使用Postman进行测试。使用Swagger可以保持接口文档能够及时更新。