ASP.NET WebAPI在线接口文档HelpPage和Swagger实战演练手册
一、课程介绍
你需要为客户编写Api调用手册？你需要测试你的Api接口？你需要和前端进行接口对接？那么这篇文章应该可以帮到你。 项目使用采取前后端分离的方式，后台提供API接口给前端开发人员。这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用word或markdown等文档方式进行交流，实际操作中却很少动手去写。为了解决api接口文档生成的这个问题，目前有两种方案。
1、微软自带的Microsoft.AspNet.WebApi.HelpPage
2、第三方在线接口文档上成工具swagger。
1.1、本次分享课程环境说明
1）、Visual Studio 2019企业版。
2）、.Net Framwork 4.7.2。
1.2、正确的学习课程方式须知
1）、视频+实例源代码配套学习，一千个读者就有一千个哈姆雷特，仁者见仁智者见智！
2）、基础理论和实战演练相结合，切记眼高手低。
3）、在学习的过程中，我们少一点抱怨，将多一份收获。
如果您在学习过程中遇到任何的课程问题，请先私下直接找阿笨老师进行在线的沟通和交流。谢谢大家的理解和支持，预祝大家学习快乐！
如果您同样对本次分享《ASP.NET WebAPI在线接口文档HelpPage和Swagger实战演练手册》课程感兴趣的话，那么请跟着阿笨一起学习吧。
废话不多说，直接上干货，我们不生产干货，我们只是干货的搬运工。
二、概念名称含义介绍
2.1、什么是Swagger？
Swagger是一种Rest API的简单但强大的表示方式，她是标准的与语言无关，这种表示方式不但人可读，而且机器可读。 可以作为Rest API的交互式文档，也可以作为Rest API的形式化的接口描述，生成客户端和服务端的代码。
2.2、在线接口文档生成工具那么多，为什么选择Swagger的原因？
Swagger能成为最受欢迎的REST APIs文档生成工具的原因：
Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。
三、ASP.NET Web API在线接口文档实战演练手册
3.1、ASP.NET Web API中如何使用HelpPage文件生成工具
1、在Nuget添加Help Page组件。（如果采用建立的WEBAPI模板创建项目，默认已经自动的添加了）
nuget install-package Microsoft.AspNet.WebApi.HelpPage
2、在Nuget添加Test Client组件。
nuget install-package WebApiTestClient 或者nuget install-package WebApiTestOnHelpPage
在Areas\HelpPage\Views\Help\Api.cshtml文件最某位位置添加以下代码：
@Html.DisplayForModel("TestClientDialogs")
@section Scripts {
<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
@Html.DisplayForModel("TestClientReferences")
}
3、如何解决在实际分层项目开发中的多项目类库文档注释显示的问题。
3.2、ASP.NET Web API中如何使用Swagger文件生成工具
NuGet上引用Swashbuckle
添加Swagger Nuget包 Swashbuckle
nuget install-package Swashbuckle
Swashbuckle是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI显示出来
在使用swagger的过程中，产生了一些小问题，例如：汉化、查询、控制器备注。
配置到后swagger的访问地址如下：
https://localhost:44330/swagger/ui/
四、总结
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。而我最近做的项目用的是WebAPI,前后端完全分离，这时后端使用Swagger就能够很方便简洁的把所写的接口以及相关注释展示给前端人员，从而方便双方的沟通，提高工作效率。
Swagger方便简洁，能够很大的提高我们的工作效率，还是值得一用的。阿笨分享的手册只是一些企业比较实用的功能点,Swagger的高级功能还有很多，比如文件上传，身份认证等等，这些就需要大家去慢慢摸索了。推荐一款Api 是高效、易用、功能强大的 api 管理平台,旨在为开发、产品、测试人员提供更优雅的接口管理服务—Yapi。
最后送大家一句话：希望大家在.NET开发的学习道路上一直跟着阿笨坚持下去吧！
