在现代软件开发中,API文档是确保开发者能够正确、高效地使用API的关键。OpenAPI规范提供了一种标准化的方式来描述RESTful API,而Swagger UI则是一个流行的工具,用于以用户友好的方式展示这些文档。本文将介绍如何使用Avantation工具从HTTP存档(HAR)文件生成OpenAPI规范的YAML文件,并通过Swagger UI来展示这些文档。
步骤1:使用Avantation生成OpenAPI YAML文件
Avantation是一个工具,可以从HAR文件生成OpenAPI 3.0规范。HAR文件是一种JSON格式的文件,用于记录浏览器与服务器之间的HTTP交互。
首先,你需要安装Avantation。如果你已经安装了Node.js,可以通过npm来安装Avantation:
npm install -g avantation
然后,你可以使用Avantation来处理HAR文件并生成OpenAPI规范的YAML文件:
avantation path/to/your/harfile.har -o path/to/output/openapi.yaml
这个命令会读取HAR文件,并根据其中的HTTP请求生成OpenAPI规范,然后将结果保存到指定的YAML文件中。
步骤2:创建index.html加载OpenAPI.yaml
一旦你有了OpenAPI规范的YAML文件,下一步就是使用Swagger UI来展示这些规范。首先,你需要下载Swagger UI的发行版。你可以从Swagger UI的GitHub仓库中获取:
https://github.com/swagger-api/swagger-ui/releases
下载并解压Swagger UI后,找到index.html
文件。你需要编辑这个文件,让它指向你的OpenAPI YAML文件。找到index.html
中的以下脚本并进行修改
HTML代码
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="https://your-web-site/public/swagger-ui/swagger-ui.css" >
<link rel="icon" type="image/png" href="https:///your-web-site/public/images/swagger_icon.png" sizes="16x16" />
<link rel="stylesheet" type="text/css" href="https:///your-web-site/public/css/swagger_doc.css">
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body
{
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div style="border-bottom: 2px solid rgba(0,0,0,.15); background-color:#ffffff">
<div class="swagger-header-div">
<table style='width: 98%'>
<tr>
<td><img class="header-img" src="/public/images/swagger_icon.png"></img><p class="header-title"><strong></strong></p></td>
<td style='width:82%; text-align:right'><iframe id='rd'></iframe></td>
</tr>
</table>
</div>
</div>
<div id="swagger-ui"></div>
<script src="https:///your-web-site/public/swagger-ui/swagger-ui-bundle.js"> </script>
<script src="https:///your-web-site/public/swagger-ui/swagger-ui-standalone-preset.js"> </script>
<script src="https:///your-web-site/public/js/swagger_doc.js"> </script>
<script>
const DisableTryItOutPlugin = function () {
return {
statePlugins: {
spec: {
wrapSelectors: {
allowTryItOutFor: () => () => false
}
}
}
}
}
window.onload = function() {
select_option_onload();
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "openapi.yaml",
validatorUrl: null,
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl //,
// DisableTryItOutPlugin,
],
layout: "StandaloneLayout",
tryItOutEnabled: true,
requestInterceptor: (request) => {
request.rejectUnauthorized = false;
return request;
}
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body>
</html>
确保将url
参数的值替换为你的OpenAPI YAML文件的实际路径。
步骤3:使用Python的SimpleHTTPServer发布网页
由于直接从文件系统访问HTML文件在某些浏览器中受到限制,你需要通过一个本地服务器来提供Swagger UI页面。Python的SimpleHTTPServer是一个简单的选择。在包含index.html
的目录中运行以下命令:
# Python 2.x version
python -m SimpleHTTPServer 8000
# Python 3.x version
python3 -m http.server 8000
这将在端口8000上启动一个HTTP服务器,然后你可以通过浏览器访问来查看你的API文档。
结论
通过结合使用Avantation和Swagger UI,你可以轻松地从HTTP请求日志中生成并展示OpenAPI文档。这个过程不仅节省了手动编写文档的时间,而且还可以确保文档的准确性和最新性。对于需要快速迭代和发布API的团队来说,这种自动化方法是一个巨大的时间节省者。