1、什么是Swagger?
Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful API,它是为了解决Web API生成有用文档和帮助页的问题。
2、为啥选用swagger?
1)它具有交互式文档、客户端SDK生成和API可发现性等优点。
2)书写api说明文档的工具有很多,但是能称之框架只有swagger
3、Swagger 规范 (swagger.json)
Swagger 流的核心是 Swagger 规范,默认情况下是名为 swagger.json 的文档。 它由 Swagger 工具链(或其第三方实现)根据你的服务生成。 它描述了 API 的功能以及使用 HTTP 对其进行访问的方式。 它驱动 Swagger UI,并由工具链用来启用发现和客户端代码生成。
4、ASP.NET Core 使用Swagger生成api说明文档
4.1引用Nuget包,“Swashbuckle.AspNetCore”
![](https://img2018.cnblogs.com/blog/1234201/201906/1234201-20190612151531959-771213810.png)
Swashbuckle.AspNetCore 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档。
Swashbuckle 有三个主要组成部分:
- Swashbuckle.AspNetCore.Swagger:将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
- Swashbuckle.AspNetCore.SwaggerGen:从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合,以自动公开 Swagger JSON。
- Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。
4.2添加并配置Swagger中间件
在Startup.cs类中,编辑ConfigureServices方法
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1.0", new Swashbuckle.AspNetCore.Swagger.Info
{
Title = "My WebAPI",
Description="API说明文档",
Version = "V1.0",
Contact=new Swashbuckle.AspNetCore.Swagger.Contact { Name="Blog.Core"}
});
});
}
4.3在Startup.cs类中Configure 方法中,启用中间件生成Json文档和SwaggerUI提供服务
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web API");
});
app.UseMvc();
}
到此,已经完成Swagger的添加,启动项目,在端口后面输入/Swagger,然后回车,就可看到生成API文档效果了
![](https://img2018.cnblogs.com/blog/1234201/201906/1234201-20190613134659008-770180175.png)
![](https://img2018.cnblogs.com/blog/1234201/201906/1234201-20190613134736478-245336453.png)
注意:如果ConfigureServices 方法中的 services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1.0"的V1.0, 和Configure 方法中的app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web API");
})的V1不一致,将会出现下面的bug
![](https://img2018.cnblogs.com/blog/1234201/201906/1234201-20190613134745947-1102021794.png)
5、总结
通过本篇文章的简单介绍,我们可以简单了解到:
1、什么是Swagger?
2、swagger的优点。
3、ASP.NET Core 使用Swagger生成api说明文档。
4、ASP.NET Core使用Swagger中常遇到的错误
源码已经放到Github上面,地址是:https://github.com/xiaoerhao/Blog.Core
扫描二维码关注公众号,回复:
6451469 查看本文章
![](/qrcode.jpg)
写博客也是为了督促自己学习和记录学习的内容,最后感谢"老张的哲学"对于知识的分享,很多时候都是在他们这些前辈的基础上去学习,下一次再分享关于swagger api文档注释和汉化。