本文为一系列文章的序章，内容纯原创。
传统自动化文档
根据我几年的学习经验，目前比较流行的自动化文档生成主要通过以下形式实现：
- 通过代码中的注释，自动化生成web文档界面
- 通过规范化的命名和参数，或者注解之类的额外代码自动化生成
以上的两种方式，都有非常明显的人为的付出，但相比较人工写文档有明显的优势：
- 文档规范化
- 在修改API的实现逻辑的时候，可以顺手修改文档
当然劣势也是存在的：
- 需要付出学习成本
- 文档不一定准确
- 历史遗留的代码需要付出相当大的劳动量才能支持文档自动化生成
那么是否有更加先进的自动化文档生成方案?
自动化API文档生成方案(黑盒)
相比较前面较为传统的文档生成方式，这种新的方式有以下优点:
- 几乎没有学习成本，只要正常搭建好环境，就可以自动化生成相关的文档
- 文档的生成没有人工参与
- 适用范围广，不依赖于语言，框架
好了，言归正传，这种自动化文档生成方式到底是如何实现？
文章的标题上的黑盒，指在测试中就是不关心具体实现，只考虑API的功能。
第一部分：
信息采集
代理对于服务器和客户端是透明的，所以可以非常简单的部署，不会干涉到具体的实现。
笔者使用 flask+requests 开发代理服务器，用mongodb作为记录数据库。
记录每次访问的请求参数和返回结果
第二部分
模型构建：通过记录下的信息，构建API模型
在模型构建之前，需要先了解API的具体模型表示，下面的内容是根据笔者的工作经验总结的，并不能代表所有情况
笔者就职的公司，API开发规范是使用POST 和 form-data 格式请求，并返回json格式，所以具体的开源项目可能有所局限，如果有感兴趣的同学欢迎PR
url 路由
url 里面可能带有参数等信息
header 请求头
其中包含用户，安全和环境有关的信息
data 参数
请求附带的请求参数，比如form表单
其抽象格式为：(key:value)对
api的参数可以有一下的分类(本项目可以自动化的构建一下分类的相关信息)
- 必选参数，可选参数，n个可选参数必选一个
- int,float,str,bool 这些基本类型 list,dict 列表，字典类型
- 用户来源，api中间沟通，校验
- 用户来源 ： 这个参数的具体内容由用户决定，其具体又有 有限 和无限之分。有限 指参数的值是有限的。无限 指 这个参数完全由用户提供的内容，比如 评论的内容 等
- api中间沟通 ： 比如 文章的id ，由 文章列表 这个api 提供 文章id列表，之后 文章详情 通过列表内的id访问完整的内容
- 校验 : 参数用于安全校验或者由系统决定
返回值(json)
本项目目前仅支持 json 格式的api校验
返回值有以下分类:
- 元数据(返回码) ，消耗数据(用户界面展示，并不作为参数发回)，通道数据(将发回给服务器)
- int,float,str,bool 基础类型，list,dict 列表和字典类型
- 校验参数，用于客户端验证服务器
文档展示
这是给人看的，将模型转换成文档。
笔者的思路是写一个文档模板，然后模型套进去，生成 markdown 的文件。
更多内容明天再更新，开源仓库等我整理下代码再发出来
