【Swagger】Swagger Editor学习分享

“Swagger Editor”顾名思义是一个编辑器，那“swagger”又是什么呢？

Swagger是什么

Swagger 是一个功能强大的框架，用于设计、构建、归档、调试 RESTful 风格的API。它包含一套描述RESTful API 的规范格式（Swagger Specification）和若干个实用工具（Swagger Editor、Swagger Codegen、Swagger UI）等。Swagger 的目标是定义一个标准的、语言无关的 RESTful API 接口，不须要阅读源码和文档，就可让开发者和机器可以发现和理解服务的接口。 本文主要是关于 Swagger Editor 的学习和分享。

Swagger Editor 的安装

Swagger Editor 官网有安装步骤，网上也相关的教程，不过我安装的过程当中老是碰到一些莫名其妙的错误，致使安装失败。通过摸索，仍是本身总结出了经验，仅供参考。

首先，Swagger Editor 的运行依赖 Node JS，因此本地要先安装 node 环境。node 安装好之后，在命令行运行查看 node 是否安装成功。

node -v

查看 npm 版本，npm是随同NodeJS一块儿安装的包管理工具，能解决NodeJS代码部署上的不少问题，相似于Cent OS上的yum。

npm -v

因为网络缘由，用npm安装包可能会比较慢，可使用国内的淘宝镜像。命令行执行

npm install cnpm -g --registry=https://registry.npm.taobao.org

以后就能够用 cnpm 命令代替 npm 命令了。

而后，在 GitHub 上下载 swagger-editor，不过打包好的文件老是下载失败，只能下载原码，本地打包原码又会报不少看不懂的错误，怎么办呢？ 咱们能够用 npm 来得到 swagger-editor。在命令行执行

npm install swagger-editor

就会在当前目录的 node_module 文件夹下看到 swagger-editor 了。

另外，还须要一个http服务器来加载项目中的静态文件，通常能够用http-server。命令行执行

npm install -g http-server

全局安装http-server。安装好之后，在 swagger-editor 所在目录用命令行执行

http-server -p 8000 swagger-editor

-p 是指定访问端口，在浏览器中访问 http://localhost:8000 就能进入编辑页面了。

或者用文本编辑器打开 swagger-editor 文件夹下的package.json，找到

"scripts": {
    "start": "node server.js",
}

修改成

"scripts": {
    "start": "http-server -p 8000",
}

而后打开命令行，切换到 swagger-editor 目录下，执行

npm start

就能启动项目了。

也能够用 tomcat 来部署 Swagger Editor，将 Swagger Editor文件夹放到 tomcat 的 webapp 目录下，启动tomcat，而后在浏览器访问 http://localhost:8080/swagger-editor

Swagger Editor 的使用

Swagger Editor 使用 yaml 格式描述 API，它的编辑界面相似于Markdown，左边是文本，右边是预览页面，能够实时显示编辑效果和格式校验。

Swagger Editor 还能自动生成不一样平台的服务端和客户端，方便先后端开发人员进行测试。

服务端

如图，以Spring项目为例，生成一个Spring架构的服务端，在Eclipse中导入项目。

因为该项目使用了spring-boot，咱们能够从 Swagger2SpringBoot 直接启动项目，默认端口是8080。 在 API 编辑页面每一个接口的下面有个 “Try this operation” 按钮，点击会展开测试 API 的界面，可编辑协议、accept类型、参数等。

在左侧 API 编辑页面把 host 改成本地服务地址，填写参数后点击 Send Request，请求就能发送到服务端了。 可是可能会出现跨域问题，致使请求的响应失败。

警告的最后有解决的办法

⚠️ This is a cross-origin call. Make sure the server at localhost:8080 accepts GET requests from localhost:8000. Learn more

这里我选择在服务端启用 CORS 的方法，就是在 response 的 header 中设置

Access-Control-Allow-Origin: editor.swagger.io

Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

这两项。

服务端的代码中已经有了这样一个过滤器 ApiOriginFilter，可是彷佛没起做用。缘由是这个类上面没加 @Component 注解。 加上注解以后，重启服务，浏览器就能收到正确的响应了。

客户端

选择语言生成客户端，导入项目，修改 ApiClient 中的服务地址

而后跑单元测试就行了。