Swagger是一种流行的API文档化工具，可以通过生成API文档和使用该文档交互的方式简化API测试和开发。在Swagger中，访问地址是指API描述文件。本文将从几个方面深入探讨Swagger访问地址的作用、用法以及相关的示例代码。
一、创建Swagger访问地址
我们可以在使用Swagger之前创建Swagger访问地址。Swagger访问地址是使用Swagger UI来访问API文档的URL。在许多情况下，这个URL直接由API的发布者提供。
使用下面的代码，定义一个基本信息对象和一个路径对象，并将它们合并成OpenAPI规范对象。这将是一个基本的示例，用于描述API的Swagger访问地址。
const OpenApi = {
"openapi": "3.0.0",
"info": {
"title": "API",
"version": "1.0.0"
},
"paths": {
"/api/users": {
"get": {
"summary": "Get a list of users",
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
};
在Swagger UI中这个URL的显示将如下所示，我们可以非常容易地了解到API的信息:
二、获取Swagger访问地址
创建好Swagger访问地址后，我们需要获取Swagger访问地址。这可以通过将Swagger UI包含在应用程序中实现。
使用下面的代码，打开Swagger UI，将Swagger访问地址传递给它，并将UI显示在页面中：
//引用SwaggerUI的JavaScript文件
<script src="https://unpkg.com/swagger-ui-dist@3.4.0/swagger-ui.js"></script>
//获取DOM元素
const uiContainer = document.getElementById('swagger-ui');
//获取Swagger访问地址
fetch('/swagger.json')
.then(response => response.text())
.then(data => {
const spec = JSON.parse(data);
const ui = SwaggerUIBundle({
spec: spec,
dom_id: '#swagger-ui'
})
window.ui = ui
});
这样，我们就可以使用Swagger UI来访问和测试API。下面是Swagger UI的一张示例截图：
三、自定义Swagger访问地址
在Swagger UI中，我们可以自定义Swagger访问地址和相应的UI。这可以很大程度上提高API文档的可读性。
使用下面的代码，我们可以通过设置调节Swagger UI中的访问地址的路由，自定义Swagger访问地址:
// 引用SwaggerUI的JavaScript文件
<script src="https://unpkg.com/swagger-ui-dist@3.4.0/swagger-ui.js"></script>
//获取DOM元素
const uiContainer = document.getElementById('swagger-ui');
//引用Swagger的JavaScript文件
const swaggerJsonUrl = '/swagger.json';
//添加UI配置对象以自定义UI
const uiConfigObject = { url: swaggerJsonUrl, docExpansion: 'list', tagsSorter: 'alpha' };
//设置SwaggerUI的路由
const customRoutes = {
validate: false,
urls: [
{ url: "/api/docs", name: "API Doc" },
{ url: "/api/redoc", name: "API Redoc" },
{ url: "/api/custom-swagger", name: "Custom Swagger UI" }
]
};
通过设置一个自定义路由，我们可以轻松访问到自定义的Swagger UI。下面是一个示例截图：
四、使用Swagger Editor编辑Swagger访问地址
Swagger Editor是一个在线编辑器，可以帮助我们更轻松地创建Swagger访问地址。在Swagger Editor中，我们可以将许多定义组合在一起，并在Swagger UI中使用这个规范。Swagger Editor还带有实时呈现和文档化工具。
使用下面的代码，我们可以在Swagger Editor中编辑Swagger访问地址：
//引用Swagger Editor的网页地址
const swaggerEditorPath = 'https://editor.swagger.io/?url=';
// 获取Swagger访问地址
const swaggerJsonUrl = '/swagger.json';
const encodedJsonUrl = encodeURIComponent(swaggerJsonUrl);
const swaggerEditorUrl = `${swaggerEditorPath}${swaggerJsonUrl}`;
//使用窗口打开编辑器
const editorWindow = window.open(swaggerEditorUrl, "Swagger Editor");
editorWindow.focus();
这样，我们就可以打开Swagger Editor，开始创建和编辑Swagger访问地址。下面是Swagger Editor的一张示例截图：
五、通过Swagger安全控件保护Swagger访问地址
访问Swagger访问地址通常需要授权。通过Swagger安全控件，我们可以在Swagger中完成身份验证和授权操作，从而保证访问安全性。
下面是保护Swagger访问地址的示例代码：
//引入Swagger中的设置
const security = [
{
ApiKeyAuth: []
}
];
//API授权
SwaggerUIBundle({
spec: spec,
dom_id: '#swagger-ui',
deepLinking: true,
displayOperationId: false,
defaultModelsExpandDepth: -1,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl,
SwaggerUIBundle.plugins.SwaggerJsUrl,
SwaggerUIBundle.plugins.ConfigsPlugin
],
layout: 'BaseLayout',
configsPlugin: {
authActions: {
ApiKeyAuth: {
logout: (auth) => { console.log('Logout', auth) },
onLoggedIn: (auth) => { console.log('Logged In', auth) }
}
},
security,
codeGeneratorOptions: {
includeSchemes: true,
includeProducesConsumes: true,
includeProducesAndResponseTypes: true
},
useResCallback: true,
opsStateResponses: true
}
})
上述代码可以保证我们在访问Swagger访问地址时能够进行安全控制操作。下面是一个例子截图：
六、总结
Swagger是一个流行的API文档化工具，可以通过生成API文档和使用该文档交互的方式简化API测试和开发。Swagger访问地址是指API描述文件。本文从创建Swagger访问地址、获取Swagger访问地址、自定义Swagger访问地址、使用Swagger Editor编辑Swagger访问地址以及通过Swagger安全控件保护Swagger访问地址等多个方面阐述了Swagger访问地址的作用、用法以及相关示例代码。让我们深入了解Swagger访问地址以提高我们对Swagger的使用效率。
