SwaggerUIBundle：指定基础 url

Question

我需要测试 api 其中：


API Url	http://api.mydomain.loc:20109/v1/
API Definition URL	http://api.mydomain.loc:20109/v1/swagger/swagger.json

API 定义是：

{
  "openapi": "3.0.1",
  "info": {
    "title": "***",
    "description": "***",
    "version": "v1"
  },
  "servers": [
    {
      "url": "/v1/path1/path2"
    }
  ],
  "/ressource1": {
      "get": {
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
  ...
}

我按照 documentation 中的这部分 unpkg 来启动本地 Swagger UI。我使用以下内容创建文件“swagger-ui.html”：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta
    name="description"
    content="SwaggerIU"
  />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'http://api.mydomain.loc:20109/v1/swagger/swagger.json',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>

当我打开页面时，API 定义被正确加载并显示 Swagger UI。但是当我尝试端点“ressource1”时，Swagger UI 调用“http://api.mydomain.loc:20109/v1/path1/path2/ressource1”。就我而言，我想调用“http://api.mydomain.loc:20109/v1/ressource1”。

如何使用 unpkg 覆盖 Swagger UI 中的基本路径？

Answer 1

Swagger UI 具有参数 spec :

spec : A JavaScript object describing the OpenAPI definition. When used, the url parameter will not be parsed. This is useful for testing manually-generated definitions without hosting them.

解决方案是手动加载 api 定义，编辑定义并将编辑后的定义传递给 Swagger UI :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta
    name="description"
    content="SwaggerIU"
  />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  const swaggerUrl = "http://api.mydomain.loc:20109/v1/swagger/swagger.json"
  const apiUrl = "http://api.mydomain.loc:20109/v1/"
  window.onload = () => {
    let swaggerJson = fetch(swaggerUrl).then(r => r.json().then(j => {
      console.log('\nREQUEST 2',j)
      j.servers[0].url = apiUrl;
      window.ui = SwaggerUIBundle({
        spec: j,
        dom_id: '#swagger-ui',
      });
    }));
  };
</script>
</body>
</html>

您可以复制此代码并仅编辑 swaggerUrl 和 apiUrl 中的值。

Answer 2

这是另一个使用 plugin with rootInjects. The main idea is the same as in 的解决方案 - 动态更新 OpenAPI 定义。

<!-- index.html -->

<script>
const UrlMutatorPlugin = (system) => ({
  rootInjects: {
    setServer: (server) => {
      const jsonSpec = system.getState().toJSON().spec.json;
      const servers = [{url: server}];
      const newJsonSpec = Object.assign({}, jsonSpec, { servers });

      return system.specActions.updateJsonSpec(newJsonSpec);
    }
  }
});

window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "http://api.mydomain.loc:20109/v1/swagger/swagger.json",
    ...

    // Add UrlMutatorPlugin to the plugins list
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl,
      UrlMutatorPlugin
    ],

    // This will set appropriate data when Swagger UI is ready
    onComplete: () => {
      window.ui.setServer("http://api.mydomain.loc:20109/v1")
    } 
  });

  window.ui = ui;
};
</script>

SwaggerUIBundle：指定基础 url

SwaggerUIBundle : Specify base url

swagger-ui