Swagger工具组件Swagger-ui的介绍及使用

1、Swagger-ui介绍

Swagger-ui 是一套 HTML/CSS/JS 框架，用于渲染 Swagger 文档，以便提供美观的 API 文档界面。

也就是说，Swagger-ui 是一个 UI 渲染工具。

2、安装和使用

到https://github.com/swagger-api/swagger-ui下载最新的 swagger-ui 。

git clone https://github.com/swagger-api/swagger-ui.git

下载完成后，单独部署到你自己的 Web 服务器即可。

swagger-ui/dist/index.html 文件是 swagger-ui 项目的入口文件，故你需要将 Web 服务器的根目录指向 swagger-ui/dist。

这种将 swagger-ui 单独部署为一个项目的做法，会产生跨域的问题。比如，你调试 API 时，报错信息为：

这很有可能就是跨域问题导致的。

这里，我们使用 CORS（跨源资源共享）来解决跨域问题，这样的话，就只需改动服务器端代码，而无需改动客户端代码，而且 CORS 支持各种请求类型。

通过 CORS 来解决跨域问题的基本思路是在服务器端添加响应头：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Key, Authorization

CORS 请求中的非简单请求会先发送一次预检请求（请求类型为 OPTIONS），再发送正式的请求。

为了防止非简单请求的两次请求产生重复操作的问题（比如同时添加了两篇文章），最好将预检请求的路由单独写。

在 Laravel 中，可以这样写：

Route::options('articles/{article?}', function () {                 // 预检请求单独写，否则，可能出现重复操作的问题
    return response()->json([])                                     // 预检请求返回一个空数组即可
        ->header('Access-Control-Allow-Origin', '*')
        ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
        ->header('Access-Control-Allow-Headers', 'Content-Type, Key, Authorization');
}); 

如果你对跨域请求还不明白，可参考https://blog.csdn.net/lamp_yang_3533/article/details/79944441。

当然，如果你不想跨域，就将 Swagger-ui 集成到你的 API 项目中。只需拷贝 Swagger-ui/dist 目录即可。

关于 Swagger-ui 的更多细节，请参考官网https://swagger.io/docs/swagger-tools/。

更改默认的渲染文档

Swagger-ui 默认渲染的是http://petstore.swagger.io/v2/swagger.json， 它是官方提供的一个 Demo。

如果你已经编写好了自己的 Swagger 文档，可以进行更换。

只需修改 swagger-ui/dist/index.html 文件，将

url: "http://petstore.swagger.io/v2/swagger.json", 

更改为

url: "openapi.yaml", 

openapi.yaml 是我编写的 Swagger 文档，由于我已经将其拷贝到了 swagger-ui/dist 目录中，所以可以这么写。

然后，在浏览器中访问 Swagger-ui 项目，就可以看到你的 Swagger 文档被渲染后的 UI 界面。