手动编写Swagger文档与部署指南

Swagger介绍

在Web开发中，后端开发者在完成接口开发后，需要给前端相应的接口使用说明，所以一般会写一份API文档。一般来说，有两种方式提供API接口文档，一种是利用插件在代码中自动生成，另一种是手工编写API文档。

Swagger就是为API文档设计而生的，其中包含一整套相关工具，既支持利用插件在代码中进行注解从而自动生成文档，也支持手工编写文档。两种方式各有优缺点：

• 自动生成：省时，方便。只需在编写代码的时候添加一点注解就可以帮你自动完成文档的生成和部署。但是缺点也很明显，对于比较复杂的接口，或者在参数中使用自定义参数解析器的接口，它的支持就不太完美，换句话说，生成的文档很“死板”，里面可能有很多与预期不太符合的东西。（期待相关插件功能越来越完善，我相信有一天会完全取代手工编写的方式）。
• 手工编写：灵活性高，能够完美的表达自己的想法。缺点就是需要额外的编写，维护和管理。

接下来我对两种方式分别做一下介绍。

自动生成

自动生成的方式还是比较容易的，对于不同的语言，有不同的插件以供使用。

• 如果你的后台用node编写，可以使用koa-swagger-decorator来生成API文档。
• 如果你的后台采用spring-boot方案，可以用springfox开发的一套插件来生成Swagger文档。具体可以参考这个教程。
• 对于其他技术路线，读者可以自行Google搜索是否有相关插件以供使用。

接下来我主要讲解一下手工编写的方式。

手工编写

后台开发者在完成接口开发后，需要进行如下流程：

1. 在Swagger Editor中编写swagger.yaml文件（具体语法见官方教程，比较简单）.
2. 在Swagger Editor中将yaml文件导出为json文件。
3. 利用Swagger UI渲染json文件，并且部署在服务器上。

其中前两点比较容易，有比较好的参考教程，一步步走下来就行。而利用Swagger UI渲染并部署，稍微麻烦一些，下面我将自己的做法给大家分享一下。

首先，在开始之前，可以看看我们项目组的一个示例。这个 Swagger 是我部署上去的，可以比较方便的查看，并且利用Try it out功能可以进行实时的测试，这也是利用Swagger编写API文档很大的一个好处。

接下来正式讲解如何使用Swagger UI渲染json文件，并且部署在服务器上。

Swagger-UI的官方仓库里明确说明了：他们在npm仓库里上传了两个npm模块，分别是swagger-ui 和 swagger-ui-dist. 这两种方式都需要npm的支持，也就是说我们需要在服务器上运行一个node程序来专门为swagger服务，特别是当我们的服务器端不是用node.js写的时候，需要额外花费较大的精力和时间。那么我们有没有办法 不使用任何node.js库，直接将Swagger UI部署在云端呢？ 答案当然是有的，我们只需要充分利用官方仓库中的/dist文件夹即可。具体步骤如下：

1. 首先我们进入Swagger-UI的官方仓库，将其克隆至本地.
2. 进入仓库中的/dist文件夹，用浏览器打开index.html文件，这个时候，应该可以看到官方的Swagger PetStoreAPI实例文件已经打开并且成功渲染。
3. 将我们撰写的json文件上传到云端服务器上。确保能够远程访问。(例如您可以尝试我上传的http://121.42.175.137/swagger.json, 能够到达这个效果就算成功）
4. 用编辑器打开2中的index.html文件，将onload function中的url:"https://petstore.swagger.io/v2/swagger.json"改为自己服务器上json文件的URL。
5. 再次用浏览器打开index.html，成功访问到我们自己的API文档。
6. 将dist文件夹整个上传到云端服务器，即全部完成。

这个方法是我自己摸索出来的，主要是利用了dist文件夹已经拥有渲染json文件的全部能力，这里包含了所有的html, css, js，于是我们可以直接拿来用了～当然这样也有一点缺陷，就是更新会不及时。官网上偶尔会更新dist文件夹，而我们的dist文件夹是不会自己更新的，但是也没有太大关系。

本机渲染

以上方法基于拥有远程服务器的前提。如果您想用此方法在本机上渲染json，同样也是有方法的，只需要利用http-server或其他的本地服务器程序，将json文件挂到本机某一端口（例如8080），然后将index.html中的url改为localhost:8080/xxx.json即可。