使用Swagger 写文档是比较方便的。通常有通过代码生成，和直接写Yaml或者JSON文件。本文主要介绍使用Yaml或者JSON写Swagger文档。
下载Swagger UI
从https://github.com/swagger-api/swagger-ui下载代码，并把dist目录内容拷贝出来。
修改index.html
Index.html内容如下（仅包含body 标签部分部分）
<body>
<div id="swagger-ui"></div>
<script src="./swagger-ui-bundle.js"> </script>
<script src="./swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body>
修改文件的body标签部分为以下内容
<body>
<div style="background-color: #1f1f1f">
<select id="api-select"></select>
</div>
<div id="swagger-ui">
</div>
<script src="./swagger-ui-bundle.js"> </script>
<script src="./swagger-ui-standalone-preset.js"> </script>
<script>
let sites = [
{name: 'site A', url: 'https://petstore.swagger.io/v2/swagger.json'},
{name: 'site B', url: './mydoc.yaml'}
]
window.onload = function() {
let selectUrl = function(url) {
let ui = SwaggerUIBundle({
url: url,
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});
window.ui = ui
}
selectUrl(sites[0].url)
let items = document.getElementById('api-select');
sites.forEach(site => {
let option = document.createElement('option')
option.innerHTML = site.name
option.value = site.url
items.appendChild(option)
});
items.onchange = function() {
let valOption = this.options[this.selectedIndex].value
selectUrl(valOption)
}
}
</script>
</body>
页面上就多出一个下拉框选择站点。站点的配置是在sites变量部分
let sites = [
{name: 'site A', url: 'https://petstore.swagger.io/v2/swagger.json'},
{name: 'site B', url: './mydoc.yaml'}
]
修改成你自己的内容即可。
部署
把dist目录的内容放到任何一个web服务器即可。如果你的电脑装有Python 3，可以快速部署一个站点，进入到dist目录，在命令行终端执行
python3 -m http.server
这样就生成一个端口为8000的web站点，并自动加载index.html。
Swagger
