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

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

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 界面。

推荐阅读
cjavapy编程之路首页