ASP.NET Core WebAPI帮助页--Swagger简单使用1.0

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”

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文档效果了

注意：如果ConfigureServices 方法中的 services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1.0"的V1.0, 和Configure 方法中的app.UseSwaggerUI(c => {

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web API");

})的V1不一致,将会出现下面的bug

5、总结

通过本篇文章的简单介绍，我们可以简单了解到：

1、什么是Swagger？

2、swagger的优点。

3、ASP.NET Core 使用Swagger生成api说明文档。

4、ASP.NET Core使用Swagger中常遇到的错误

源码已经放到Github上面，地址是：https://github.com/xiaoerhao/Blog.Core

写博客也是为了督促自己学习和记录学习的内容，最后感谢"老张的哲学"对于知识的分享,很多时候都是在他们这些前辈的基础上去学习，下一次再分享关于swagger api文档注释和汉化。