使用Swagger编写API文档

使用到的工具：

swagger-editor: Web版API文档编辑器，可视化输出；
swagger-codegen: 将编写好的文档文件生成服务代码；
swagger-ui：自动生成的服务中集成了swagger-ui，用于展示API文档；
swagger2markup: 将API文档(yaml格式)转换为asciidoc格式；
使用asciidoc预览工具(atom asciidoc preview或chrome asciidoc preview扩展)以html的形式预览，即可下载为pdf格式；

使用swagger-editor编写API定义文档

运行swagger-editor:

方式一：从DockerHub下载swagger-editor 镜像，启动容器：

docker pull swaggerapi/swagger-editor
docker run -d -p 8090:8080 swaggerapi/swagger-editor

方式二：从swagger-editor源码build docker镜像，启动容器：

git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
docker build -t swagger-editor .
docker run -d -p 8090:8080 swagger-editor

swagger-editor运行之后，从浏览器访问本地服务，打开swagger-editor界面，如图：

在web面板中编写API定义，页面左侧为编辑器，默认使用yaml格式，编辑后会实时更新到右侧预览面板，格式或定义错误会在编辑器具体出错行和预览面板顶部给出提示。

API定义采用的 OpenAPI规范(默认2.0，最新3.0)，具体编写格式可以参考editor自带的例子以及OpenAPI官方定义。

使用swagger-codegen生成服务代码

当API定义编写完成后，可以直接在swagger-editor界面中生成服务代码，过程如下:

点击语言及框架后，会开始下载对应版本的服务器代码。

发布API定义

当服务器代码下载完毕，可以准备开始发布API定义，过程如下：

解压源码包；
安装项目依赖(以nodejs-server为例，nodejs版本需要在4.0.0以上)：
```
cd nodejs-server-server  && npm install
```
确认服务端口并启动服务：服务入口即源码目录index.js文件，默认端口8080也在其中定义，按照需要修改即可，然后启动服务：node index.js

在浏览器中访问相应端口即可：

将API定义转换为其他格式

当前版本的swagger并没有提供相应的转换工具，如果需要将API定义输出为其他格式(如PDF)需要借助其他工具。这里介绍swagger2markup的使用，swagger2markup可以将swagger格式(OpenAPI)的API定义转换为AsciiDoc或github风格的Markdown格式，swagger2markup需要java环境，这里仍然使用docker来处理，具体过程：

下载swagger2markup镜像：

docker pull swagger2markup/swagger2markup

执行转换：

docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger.yaml -f /opt/swagger

将AsciiDoc转换为HTML或PDF:
- 使用Atom asciidoc preview工具预览AsciiDoc文件：
- 使用Atom打开AsciiDoc文件；
- 启用预览：
预览结果：
- 保存为html或pdf(需要安装转换插件)：

使用Chrom浏览器Asciidoctor.js Live Preview插件进行预览:
- 安装Asciidoctor.js Live Preview插件后，使用Chrome打开AsciiDoc文件:
- 开启插件进行预览：然后根据需要可以将页面打印为PDF格式。

以上为从定义API到按指定格式输出的完成过程，整个过程比较复杂，用到的组件比较多，如果仅仅是编写API文档可能看起来效率比较低；选择Swagger用来作为API定义工具，主要出于以下考虑：

规范：Swagger遵循OpenAPI Specification，编写出的文档有章可循，可以减少不必要的沟通；
易于测试：编写好的文档可以生成服务器和客户端代码，直接用于Mock测试；