前言
这篇文章的东西没有多么高大上，都是落地的东西，我的博客里也尽量都会把所讲的东西落地，毕竟聊的 太多空洞的东西没有太大意义，我们最终的目标还是落地。本文如果有不对的地方，或者有好的方案，欢迎各位大大即时指出来，发文的目的是总结也是希望能跟大大们一起沟通交流
历史背景
目前在xx公司做API相关的开发工作，一直以来的一个诟病就是文档无法自动化，每次有新增或者修改的时候，需要手动的去维护一份文档，来保证移动团队和第三方开发者顺利对接，尤其是在做大版本迭代的时候，几乎重构了API，导致之前的文档全部废弃，又是手动重新编辑了一份文档，写的简直欲仙欲死。这段时间有机会可以做自动化文档相当开心，终于不用被吐槽了哈哈哈。
调研相关的API文档
1.HelpPage
2.Swagger
3.RAP（还有很多类似RAP手动编写文档的 就不一一列举了）
看一下这三个是否能满足我的需求
HelpPage和Swagger都有一个问题就是如果Action的返回值是Object类型的对象，无法解析到具体的对象，首先满足不了我的需求，RAP之类的要我手动编辑果断放弃
这里多提一下Swagger 非常不错，Swagger更多的是通过ApiDescription这个类去获取里面的内容来进行解析，有兴趣的同学可以去看下Swagger，还有配套的UI，以及code-generate （支持多语言，可生成服务端以及客户端测试代码），我的下一个AspNet.Core项目在用 ，做完之后可以总结分享下。
想要达到的目的
- 明确的请求参数，包括name，type，description ，request Way，Attribute
- 清晰地返回值结果 name， type， description(如果有节点的属性是枚举，需要展示枚举的全部属性)
- 自动化测试小组和移动组对接
- 版本的差异化
- Github WebHook 持续集成，自动更新
- 通用性，改少量代码就可以给其他项目的前后端开发人员使用，不用去口头和手写文档 约定返回数据格式
具体步骤：
1.在项目的属性中进行设置生成xml ，右击项目-》属性-》生成-》勾选【XML文档文件】，可以自己选择生成后的地址，我是直接放在API文档的前端路径中
2.编写一个Action，是生成文档的主要方法，获取你的XML文件进行解析
Paste_Image.png
通过图中我们可以看见，红色标注区域是我们的主要内容，这个文档主要是通过///自动生成的注释。我们通过在其中提取一些相关的元数据信息去进行反射匹配到我们相应的Model 或者Controller之类的，读取其中的内容。
3.除了一些基本信息以外，我们其实还会有这样的需求，例如想知道我的一个API，哪些参数是必须填充的，哪些不是必须的，我的做法是通过建立接收前端的模型ReceiveModel..在属性中添加System.ComponentModel.DataAnnotations的一些属性比如 ：Required 、Range，来达到我们想要的目的
4.将解析到的内容生成一份json，我们是自己做了一个API的测试工具，然后通过文档来生成API相关的测试内容
5.后续API的更新 可以通过推送一个特定分支来进行自动化的一些工作，自动去请求一个我们编写好的Action来进行json文档的生成，直接替换前端里面之前生成好的文件
网友评论