一、技术背景
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。而前后端的唯一联系便是 API 接口，与此同时，API 文档也变成了前后端开发人员联系的纽带，变得越来越重要。Swagger 就是一款用来更好的书写 API 文档的框架。
首先让我们来看下 Swagger 的应用生态，红字部分是官网 https://swagger.io 推荐的，这里就不一一介绍了。
图1：Swagger 生态
官网中给出了 SwaggerHub 和 SwaggerHub Pro 两种开发工具，其中后者提供了若干种团队协作支持，但是需要收取一定的费用。下图是 SwaggerHub 的界面，左边是搜索框，点击信息可以跳转到相应的 OAS 代码位置；中间是 OAS 代码编辑处；右边是 API 可视化界面。
图2：Swagger Hub 界面
Springfox 则是用 Spring 构建自动的 JSON API 文档的工具，在 Java 中通过注释的形式自动生成 OAS 文档，但是现在还没有集成 Swagger 3.0。
大家可以参考 Springfox 的官方文档：https://springfox.github.io/springfox/docs/snapshot/ 来进一步的了解。
二、Swagger本地环境的配置
这里的大多数操作是在 Windows 下的 PowerShell 中完成的，给出了相应的代码。这里我建议大家新建一个文件夹，将所有下载的文件统一放置管理，相应的指令也在该文件目录下完成。
1.下载 nodejs，在官网下载最新的 Nodejs：https://nodejs.org/en/。当前常用的版本是 10.13.0。
这里需要注意的是，在 Nodejs 安装安成后会在一个新的 cmd 中自动安装相应的 package，安装过程中可能会重启电脑，而且在某些时候重启过后会提示 warning，并再次重新启动电脑，此时，只需要将打开的 cmd 窗口关闭即可，不影响后续的操作。在安装完成后，可以测试 node 和 npm（即上面说的 node 包管理器）的版本。
node -v npm -v
2.下载 Swagger-editor 和 Swagger-ui。
git clone https://github.com/swagger-api/swagger-editor git clone https://github.com/swagger-api/swagger-ui.git
3.安装 http-server ，这里我的默认 8080 端口被 Jenkins 占用了，如果需要修改则输入 http-server –p 8081 swagger-editor。
npm install -g http-server http-server –p 8081 swagger-editor
4.启动 http-server，出现如下的输出：
http-server swagger-editor
图3：配置成功提示
需要注意一点，这里我们将 swagger-editor 安装在 D 盘的 swagger 文件夹下，而非 C 盘的默认路径，在输入启动命令时需要先找到存储位置的上一级目录，如这里 cd D:Swagger。按理说在 Swaggerswagger-editor 文件目录下启动应该也可以，但是自己的电脑一直没能成功，如果有深入研究的朋友可以在评论区与我探讨。
图4：swagger-editor 存储结构
此时，便可以在网页上输入 http://localhost:808，或者输入 shell 中提示的地址登陆 Swagger-editor 了，界面如图所示。如果输入网址出错，可以先尝试更换浏览器重新进入。
http://localhost:8081
图4：Swagger-editor 界面
posted @ 2018-11-18 20:01 木瓜有益健康 阅读(...) 评论(...) 编辑 收藏
