如何在ASP.NetCore中使用Swagger

本文转载自微信公众号「码农读书」，作者码农读书 。转载本文请联系码农读书公众号。

创新互联公司是一家集网站建设,青阳企业网站建设,青阳品牌网站建设,网站定制,青阳网站建设报价,网络营销,网络优化,青阳网站推广为一体的创新建站企业，帮助传统企业提升企业形象加强企业竞争力。可充分满足这一群体相比中小企业更为丰富、高端、多元的互联网需求。同时我们时刻保持专业、时尚、前沿，时刻以成就客户成长自我，坚持不断学习、思考、沉淀、净化自己，让我们为更多的企业打造出实用型网站。

大家在开发完 webapi 后，经常为了方便接口双方对接，需要将 webapi 接口文档化，那有没有什么快捷可交互的文档呢?可以利用快捷工具 Swagger，它的可视化 UI 可轻松助你 API 文档化的同时还方便测试 API。

Swashbuckle 就是一个用于生成 Swagger 文档的开源工具包，这篇文章将会讨论如何利用 Swashbuckle 来为你的 Restful API 生成可交互的文档。

安装 Swagger 中间件

要想利用 Swagger 文档化，需要 nuget 引用 Swashbuckle.AspNetCore 包，还可以通过 Visual Studio 2019 的 NuGet package manager 可视化界面安装 或者 通过 NuGet package manager 命令行工具输入以下命令：

 
 
 
 
    
  
  
  
  
  1. dotnet add package Swashbuckle.AspNetCore 
    2.

配置 Swagger 中间件

为了配置 Swagger，在 Startup.ConfigureServices 方法中添加如下代码，注意下面的 AddSwaggerGen 方法是用于给 API 文档 添加一些元数据。

 
 
 
 
    
  
  
  
  
  1. services.AddSwaggerGen(c => 
    2. 
  
  
  
  
  2.            { 
    3. 
  
  
  
  
  3.                c.SwaggerDoc("v1", new Info 
    4. 
  
  
  
  
  4.                { 
    5. 
  
  
  
  
  5.                    Version = "v1", 
    6. 
  
  
  
  
  6.                    Title = "Swagger Demo", 
    7. 
  
  
  
  
  7.                    Description = "Swagger Demo for ValuesController", 
    8. 
  
  
  
  
  8.                    TermsOfService = "None", 
    9. 
  
  
  
  
  9.                    Contact = new Contact() { Name = "Joydip Kanjilal", 
    10. 
  
  
  
  
  10.                    Email = "joydipkanjilal@yahoo.com", 
    11. 
  
  
  
  
  11.                    Url = "www.google.com" } 
    12. 
  
  
  
  
  12.                }); 
    13. 
  
  
  
  
  13.            }); 
    14.

接下来就要启动 Swagger了，在 Startup.Configure 方法下添加如下代码：

 
 
 
 
    
  
  
  
  
  1. app.UseSwagger(); 
    2. 
  
  
  
  
  2.     app.UseSwaggerUI(c => 
    3. 
  
  
  
  
  3.     { 
    4. 
  
  
  
  
  4.         c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); 
    5. 
  
  
  
  
  5.     }); 
    6.

为了完整性，下面是 Startup 中的所有代码清单。

 
 
 
 
    
  
  
  
  
  1. using Microsoft.AspNetCore.Builder; 
    2. 
  
  
  
  
  2. using Microsoft.AspNetCore.Hosting; 
    3. 
  
  
  
  
  3. using Microsoft.AspNetCore.Mvc; 
    4. 
  
  
  
  
  4. using Microsoft.Extensions.Configuration; 
    5. 
  
  
  
  
  5. using Microsoft.Extensions.DependencyInjection; 
    6. 
  
  
  
  
  6. using Swashbuckle.AspNetCore.Swagger; 
    7. 
  
  
  
  
  7. namespace IDGSwaggerDemo 
    8. 
  
  
  
  
  8. { 
    9. 
  
  
  
  
  9.     public class Startup 
    10. 
  
  
  
  
  10.     { 
    11. 
  
  
  
  
  11.         public Startup(IConfiguration configuration) 
    12. 
  
  
  
  
  12.         { 
    13. 
  
  
  
  
  13.             Configuration = configuration; 
    14. 
  
  
  
  
  14.         } 
    15. 
  
  
  
  
  15.         public IConfiguration Configuration { get; } 
    16. 
  
  
  
  
  16.         public void ConfigureServices(IServiceCollection services) 
    17. 
  
  
  
  
  17.         { 
    18. 
  
  
  
  
  18.             services.AddMvc().SetCompatibilityVersion 
    19. 
  
  
  
  
  19.             (CompatibilityVersion.Version_2_2);    
    20. 
  
  
  
  
  20.             services.AddSwaggerGen(c => 
    21. 
  
  
  
  
  21.             { 
    22. 
  
  
  
  
  22.                 c.SwaggerDoc("v1", new Info 
    23. 
  
  
  
  
  23.                 { 
    24. 
  
  
  
  
  24.                     Version = "v1", 
    25. 
  
  
  
  
  25.                     Title = "Swagger Demo", 
    26. 
  
  
  
  
  26.                     Description = "Swagger Demo for ValuesController", 
    27. 
  
  
  
  
  27.                     TermsOfService = "None", 
    28. 
  
  
  
  
  28.                     Contact = new Contact() { Name = "Joydip Kanjilal", 
    29. 
  
  
  
  
  29.                     Email = "joydipkanjilal@yahoo.com", 
    30. 
  
  
  
  
  30.                     Url = "www.google.com" 
    31. 
  
  
  
  
  31.                 } 
    32. 
  
  
  
  
  32.                 }); 
    33. 
  
  
  
  
  33.             }); 
    34. 
  
  
  
  
  34.         } 
    35. 
  
  
  
  
  35.         public void Configure(IApplicationBuilder app, 
    36. 
  
  
  
  
  36.        IHostingEnvironment env) 
    37. 
  
  
  
  
  37.         { 
    38. 
  
  
  
  
  38.             if (env.IsDevelopment()) 
    39. 
  
  
  
  
  39.             { 
    40. 
  
  
  
  
  40.                 app.UseDeveloperExceptionPage(); 
    41. 
  
  
  
  
  41.             } 
    42. 
  
  
  
  
  42.             app.UseMvc(); 
    43. 
  
  
  
  
  43.             app.UseSwagger(); 
    44. 
  
  
  
  
  44.             app.UseSwaggerUI(c => 
    45. 
  
  
  
  
  45.             { 
    46. 
  
  
  
  
  46.                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); 
    47. 
  
  
  
  
  47.             }); 
    48. 
  
  
  
  
  48.         } 
    49. 
  
  
  
  
  49.     } 
    50. 
  
  
  
  
  50. } 
    51.

浏览 Swagger UI

现在我们运行一下应用程序来浏览一下 Swagger UI 地址，可以看到 UI 界面如下图所示，图中不同的 Http 请求使用了不同的颜色进行标识，你甚至可以在UI上直接测试不同的 api 接口。

在 Action 方法上创建xml注解

到目前为止一切顺利，在刚才生成的 swagger 文档中，并没有看到 5 个 api 接口的任何注解，这就不优雅了，如果想要在 swagger 文档上增加 xml 注解，简单粗暴的做法可以直接在 Controller.Action 顶部写上注解信息。

接下来在 ValuesController 下的每一个 Action 上都加上注解，下面就是修改后的 ValueController。

 
 
 
 
    
  
  
  
  
  1. [Route("api/[controller]")] 
    2. 
  
  
  
  
  2.     [ApiController] 
    3. 
  
  
  
  
  3.     public class ValuesController : ControllerBase 
    4. 
  
  
  
  
  4.     { 
    5. 
  
  
  
  
  5.         ///  
    6. 
  
  
  
  
  6.         /// Get action method without any argument 
    7. 
  
  
  
  
  7.         ///  
    8. 
  
  
  
  
  8.         ///  
    9. 
  
  
  
  
  9.         [HttpGet] 
    10. 
  
  
  
  
  10.         public ActionResult> Get() 
    11. 
  
  
  
  
  11.         { 
    12. 
  
  
  
  
  12.             return new string[] { "value1", "value2" }; 
    13. 
  
  
  
  
  13.         } 
    14. 
  
  
  
  
  14.  
    15. 
  
  
  
  
  15.         ///  
    16. 
  
  
  
  
  16.         /// Get action method that accepts an integer as an argument 
    17. 
  
  
  
  
  17.         ///  
    18. 
  
  
  
  
  18.         ///  
    19. 
  
  
  
  
  19.         ///  
    20. 
  
  
  
  
  20.         [HttpGet("{id}")] 
    21. 
  
  
  
  
  21.         public ActionResult Get(int id) 
    22. 
  
  
  
  
  22.         { 
    23. 
  
  
  
  
  23.             return "value"; 
    24. 
  
  
  
  
  24.         } 
    25. 
  
  
  
  
  25.  
    26. 
  
  
  
  
  26.         ///  
    27. 
  
  
  
  
  27.         /// Post action method to add data 
    28. 
  
  
  
  
  28.         ///  
    29. 
  
  
  
  
  29.         ///  
    30. 
  
  
  
  
  30.         [HttpPost] 
    31. 
  
  
  
  
  31.         public void Post([FromBody] string value) 
    32. 
  
  
  
  
  32.         { 
    33. 
  
  
  
  
  33.         } 
    34. 
  
  
  
  
  34.  
    35. 
  
  
  
  
  35.         ///  
    36. 
  
  
  
  
  36.         /// Put action method to modify data 
    37. 
  
  
  
  
  37.         ///  
    38. 
  
  
  
  
  38.         ///  
    39. 
  
  
  
  
  39.         ///  
    40. 
  
  
  
  
  40.         [HttpPut("{id}")] 
    41. 
  
  
  
  
  41.         public void Put(int id, [FromBody] string value) 
    42. 
  
  
  
  
  42.         { 
    43. 
  
  
  
  
  43.         } 
    44. 
  
  
  
  
  44.  
    45. 
  
  
  
  
  45.         ///  
    46. 
  
  
  
  
  46.         /// Delete action method 
    47. 
  
  
  
  
  47.         ///  
    48. 
  
  
  
  
  48.         ///  
    49. 
  
  
  
  
  49.         [HttpDelete("{id}")] 
    50. 
  
  
  
  
  50.         public void Delete(int id) 
    51. 
  
  
  
  
  51.         { 
    52. 
  
  
  
  
  52.         } 
    53. 
  
  
  
  
  53.     } 
    54.

打开 xml 注解

值得注意的是：Swagger 默认并不会显示 XML 注解，需要手工打开它，那怎么做呢?右键 Project，选择 Properties 后切换到 Build 页面，然后选中 XML documentation file 项 并且指定好 xml 生成的位置，参考如下：

接下来还要在 ConfigureServices 方法下将生成xml 的路径配置到 swagger 中，如下代码所示：

 
 
 
 
    
  
  
  
  
  1. c.IncludeXmlComments(@"D:\Projects\IDG\IDGSwaggerDemo\IDGSwaggerDemo\IDGSwaggerDemo.xml"); 
    2.

这就是打开 Swagger 中的 xml 注解 所需的所有事情。

指定启动url 到 Swagger UI

要想将启动项目的url指到 SwaggerUI，右键 Project 并选择 Properties，在 Debug 的 Lanuch browser 上指定 swagger 即可，如下图所示：

再次运行程序可以发现默认页就是 Swagger URL 了，如下图所示：

从图中可以看到，5个API方法后面都有相应的 xml 注解了。

Swashbuckle 是一个非常好的工具，可以简单粗暴的给 API接口生成文档，从文中也可以看出 Swashbuckle 的配置非常简单，Swagger 还有一些更高级的功能，比如通过 CSS 来定制 Swagger UI，还可以根据API的版本生成不同的 Swagger 文档，后续的文章还会跟大家介绍更多高级的功能。

译文链接：https://www.infoworld.com/article/3400084/how-to-use-swagger-in-aspnet-core.html

本文题目：如何在ASP.NetCore中使用Swagger
文章位置：http://www.stwzsj.com/qtweb/news6/8606.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联

猜你还喜欢下面的内容

域名注册知识

分类信息网

域名申请　　 　成都广告招牌　　 　成都网站建设　　 　乐山网站建设　　 　成都画册快印　　 　温江服务器租用　　 　温岭熙道网站　　 　眉山服务器托管　　 　达州网站制作　　 　乐山网站建设　　 　和县翔豪网站　　 　成都网站推广公司　　 　成都网站制作　　 　重庆企业网站建设　　 　长城雪茄　　 　梓潼做网站　　 　成都展柜定制　　 　成都定制网站　　 　成都主机托管　　 　成都服务器托管