这算是在博客园的第一篇博客吧，之后发的应该也会同步到博客园上。

此前的博客地址: https://gitbook.mytyiluo.cn

Swagger简介

Swagger是一个开源软件框架，可帮助开发人员设计，构建，记录和使用RESTful Web服务。

其中，Swagger可以生成一个交互式的API控制台，以便于快速测试API。

从个人角度讲，Swagger对于前后端分离的小团队来说是非常有帮助的。尤其是像我们这种平时没写文档习惯的人来说，Swagger能根据代码自动生成文档可谓是一大福音，再也不用被人追着问这API到底是怎么用的。

这里，我将会具体说下最近我使用Swagger的一些心得和体会，团队的开发环境如下：

• ASP.NET Core 2.1 (Visual Studio 2017 Community)
• 微信小程序 (官方工具+Visual Studio Code)

生成Swagger API 文档

对于ASP.NET Core来说，生成文档这一步还是相对容易的，且对代码基本没有侵入性。只需在Startup中配置一下即可，大致步骤基本如下：

添加NuGet包

这里，我所使用的是Swashbuckle.AspNetCore，直接用VS的NuGet包管理器下载即可。

然后在ConfigureServices中配置如下:

services.AddSwaggerGen(c => {     // 定义文档     c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" }); });

并在Configure中启用该Services：

// 使用Swagger app.UseSwagger(); app.UseSwaggerUI(c => {     c.SwaggerEndpoint("/swagger/v1/swagger.json", "Qincai API v1"); });

随后运行，打开浏览器host/swagger即可看到所生成的API文档。

若还有不清楚的，可以参考微软官方的

然后再到之前的ConfigureServices中添加如下：

services.AddSwaggerGen(c => {     c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });      // file 是你在项目属性中配置的相对路径     var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file);     c.IncludeXmlComments(filePath); });

重新生成，再运行，你可以看到Swagger中就对API以及参数添加上了注释。

添加认证功能

在实际开发中，我们常常是需要给我们的API添加上认证功能以避免非法的访问，因此我们也就需要给Swagger中的API标识上是否需要认证，并且添加提供Token的功能，以方便在Swagger的控制台中调试。

简单来说，还是在ConfigureServies中，配置如下：

services.AddSwaggerGen(c => {     c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });      var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file);     c.IncludeXmlComments(filePath);      // 定义认证方式     c.AddSecurityDefinition("Bearer", new ApiKeyScheme     {         In = "header",         Description = "请键入JWT Token，格式为'Bearer '+你的Token。",         Name = "Authorization",         Type = "apiKey"     });      // 网上为全局API添加认证参数的方法     // c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> {     
                        
关键字：