Swagger本地环境配置

一、技术背景

       随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。而前后端的唯一联系便是 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。按理说在 Swagger\\swagger-editor 文件目录下启动应该也可以，但是自己的电脑一直没能成功，如果有深入研究的朋友可以在评论区与我探讨。

图4：swagger-editor 存储结构

 

       此时，便可以在网页上输入 http://localhost:808，或者输入 shell 中提示的地址登陆 Swagger-editor 了，界面如图所示。如果输入网址出错，可以先尝试更换浏览器重新进入。

http://localhost:8081

 图4：Swagger-editor 界面