深入了解Swagger访问地址

发布时间：2023-05-21

Swagger访问地址的作用、用法及相关示例代码

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>
<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
    });
</script>

这样，我们就可以使用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>
<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" }
    ]
};
</script>

通过设置一个自定义路由，我们可以轻松访问到自定义的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的使用效率。

推荐文章