为什么需要文档自动化？

技术人员对自动化的认知主要来自于“惰性和惯性”，可以代码实现的事情就不要手工编辑，“我们不是设计师”，我们追求效率，美不美是排第二位的。so，你也会明白为啥需要文档自动化吧，毕竟除了coding，技术人员主要工作就是文档，特别是在跨团队沟通的时候，在需要把技术内容输出团队之外，或者输出自己之外的人员时候。就需要一个优雅的方式，高效的方式，以及可以炫耀的方式，所以文档自动化应运而生。

1 go-swagger依赖包下载

go-swagger中在github.com的仓库下的依赖包如下，主要包含可以对语法进行校验的govalidator，文档化的标准specification的go-openapi，还有网络处理的golang.org旗下的net和text。

go-swagger中在golang.org的包如下（这个可以到仓库github.com/golang）。

下载tips：golang.org的内容可以通过到仓库目录github.com/golang找到需要的包目录，然后可以通过git clone工具下载到本地，然后按照以下目录形式创建即可。

2 重要包介绍

go-openapi 介绍

go-openapi仓库属于openapi的一个go语言分支源码实现，那么什么是openapi呢，其实就是OpenAPI规范，即OpenAPI Specification，简称OAS，是属于Linux基金会的一个项目，主要是为了让文档化更方便，以及维护，和自动化还有服务化而服务，用来描述API格式（通过一个而配置文件格式）或者API定义的语言。其主要用于规范RESTful服务的开发过程。目前最新的版本有V3.0版本，历史版本有V2.0和V1.0，其中每个版本的Specification的说明在仓库github.com/OAI/OpenAPI-Specification/下都可以找到。在进行文档的配置文件编写的时候，如果语法报错，这个说明就是可以进行查阅参考，从而修改语法错误。

每个版本的Specification当然也是非常系统的介绍啦，不过你需要一些阅读Specificaiton的技能和技巧。比如类似RFC2119规定的key words你需要掌握其含义吧：

• "MUST" 代表“一定要出现”的意思

• "MUST NOT" 代表“一定不能出现”的意思

• "REQUIRED" 代表“必须”的意思

• "SHALL" 代表“可以有”的意思

• "SHALL NOT" 代表“可以没有”的意思

• "SHOULD" 代表“应该”的意思

• "SHOULD NOT" 代表“不应该”的意思

• "RECOMMENDED" 代表“推荐这么做”的意思

• "MAY" 代表“可能”的意思

• "OPTIONAL" 代表“可选”的意思

其中，OpenAPI文本档定义主要包含以下方面：

• 定义的URI和每个URI的操作（GET、POST等）
• 操作的参数和格式，以及输入和输出
• 认证方法
• 接口的信息，如联系方式，版本，以及使用授权等

govalidator介绍

govalidator是基于validator.js的做法，可以对Go语言的字符串、结构体以及集合进行校验和检查的工具包。那具体可以做啥呢，对于字符串我们就不说了，基本上就是自定义格式的校验和检查了。那我们来说说结构体struct，对于结构体，有了validator我们就可以做一个哦对结构体的字段属性的限制条件进行校验和判断了，可以针对字段的是否要出现和不出现，可选还是必须进行定义，可以对整型字段进行范围定义的校验，可以对字段的值进行校验等。当有了validator我们就可以对这个结构体定义的对象，进行判断（使用govalidator中的validator.Validate(obj)进行校验，如果校验出错，则还可以知道出错在哪。是不是非常高大上的技能呢，any way 我觉得至少对于代码的健壮性来说还是不错的工具吧。

3 swagger工具运行

经过编译安装完成后，swagger工具将在GOPATH工程目录下的bin目录下，为了方便可以在系统PATH环境变量添加执行swagger可执行的bin目录$GOPATH/bin。然后就可以在终端进行swagger的执行了，swagger编译完成后的功能介绍如下：

其中经常使用的命令有：

swagger validate 用于对编写的json或者yaml格式Spicification的检查和校验

swagger serve 用于对编写完成，并检查满足OpenAPI当前版本的文档配置文件（yaml或者json）进行运行部署成为服务，命令如下：

$GOPATH/bin/swagger serve --host=0.0.0.0 --port=2399 --no-open ./sdc.json

其中参数--no-open是为了限制客户端的界面打开（因为多数时候服务都是后台console执行），sdc.json是我的例子文档配置文件。运行起来后，就可以通过这个主机的ip和端口，用以下的地址进行访问：

http://hostip:2399/docs

4 配置文件校验

因为不同版本的Specificaion（从V1.0到V3.0，以及至今）对于配置文件的语法要求是不一样的，并且实用swagger进行validate校验的时候，会根据不同的语法进行。校验命令如下：

swagger validate imput.json swagger validate impurt.yml

一些出错的语法例子

例子一 属性名称写错，自动化校验并提示出来正确的是什么。

例子二 属性欠缺报错

例子三 以上例子在版本1.0下的报错

例子三 以上例子在版本3.0下的报错

5 应用和实践

方便的插件使用VS Code的Swagger插件

在VS的扩展（插件）窗口搜索swagger就会出现，swagger viewer（2.2.0）版本，选择安装即可，其中一些使用快捷键如下：

Shift + Alt + P

可以启动预览模式，一边编写配置文件，一边查看效果，还可以进行语法检查。

预览模式截图

除了插件的预览模式方便对配置文件和api接口定义方便进行编辑之外，插件也可以实时的检查语法错误，每一次保存都会触发一次语法错误校验，对于语法严重错误问题，会导致预览窗口没有内容。

根据接口定义生成客户端

需要从仓库下载swagger-editor，也可以通过把node和npm安装好之后，直接通过npm对swagger-editor进行下载。然后运行后就可以获取私有云部署的可以对api配置文档进行语法校验和检查的web版本，这个版本需要依赖于npm，你需要安装node的httpserver，然后你就可以可以部署运行校验的web服务，运行命令如下：

启动校验web服务器

以下路径中是因为我把node安装在了如此目录，所以命令是如此这般

/home/orbbec/node/node-v10.14.2-linux-x64/bin/http-server swagger-editor

备注说明：对于如何安装node的httpserver，这个需要个人去search看看教程了。

开发的文档自动化流程

在整个开发工程实践中，一个主要流程如下：

——需求-设计

然后设计又包含有——架构设计、概要设计、详细设计以及程序架构设计

还有，就是单元测试和上线测试

最后就是上生产环境和运维日常维护

那么对于文档自动化，需要在设计阶段就进行，特别是基于REST api的产品架构设计和接口设计的时候，最适合将文档设计引入，这样在设计阶段，对外部使用者来说是非常友好的，因为你提供了一个直观并且方便查阅的api文档访问地址，而不是以前低效的文件相互IM上传输。

同时对于文档自动化来说，有version的维护，只需要负责开发的人员进行版本维护即可，而且修改后还可以走一个严谨的流程进行文档配置代码的编写以及上线。但是对于使用者来说，都是系统化的，只要有修改就可以实时的看到。从而对于效率来说是非常爽的。这也是为什么需要文档自动化的根本原因。

语言实践专栏的规划，首先语言实践一定是讲述没有废话的干货，是工作中的实践，然后也还是会选择Go语言作为基础语言提供例子，然后去深层次去讲开，去从细节回归总体，去归纳出适合架构设计，程序设计，模块设计，以及框架精髓，以及语言特性的好分享和干货交流，期待每一次的分享都能给到每个人一些工作项目中的启发，方方面面的启发。所以这个专栏不会有频繁的更新，也不会无趣，以及不会说没有深度。那么为了质量，为了每一次的有价值，大概会一到两个星期更新一次吧。而且每次的内容都会有一个主题的模式：理论套路+实践（代码或者设计），等等，让我们一起期待。也欢迎随时和我沟通交流。