安装

分发渠道

NPM 注册表

我们向 npm 发布三个模块：swagger-ui、swagger-ui-dist 和 swagger-ui-react。

swagger-ui 旨在供包含模块捆绑器（如 Webpack、Browserify 和 Rollup）的 JavaScript Web 项目使用。其主文件导出 Swagger UI 的主函数，并且该模块还包含一个命名空间的样式表，位于 swagger-ui/dist/swagger-ui.css。这是一个例子

1
import SwaggerUI from 'swagger-ui'
2
// or use require if you prefer
3
const SwaggerUI = require('swagger-ui')
4

5
SwaggerUI({
6
  dom_id: '#myDomId'
7
})

有关详细信息，请参阅Webpack 入门示例。

相比之下，swagger-ui-dist 旨在供需要向客户端提供资产的服务器端项目使用。该模块导入时包含一个 absolutePath 辅助函数，该函数返回 swagger-ui-dist 模块的安装位置的绝对文件系统路径。

注意：我们建议在您的工具允许的情况下使用 swagger-ui，因为 swagger-ui-dist 会导致更多代码通过网络传输。

该模块的内容与您在 Git 存储库中看到的 dist 文件夹一致。最有用的文件是 swagger-ui-bundle.js，它是 Swagger UI 的构建版本，其中包含在一个文件中运行所需的所有代码。该文件夹还有一个 index.html 资产，可以轻松地像这样提供 Swagger UI

1
const express = require('express')
2
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
3

4
const app = express()
5

6
app.use(express.static(pathToSwaggerUi))
7

8
app.listen(3000)

该模块还导出 SwaggerUIBundle 和 SwaggerUIStandalonePreset，因此如果您在无法处理传统 npm 模块的 JavaScript 项目中，您可以执行类似的操作

1
var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle
2

3
const ui = SwaggerUIBundle({
4
    url: "https://petstore.swagger.io/v2/swagger.json",
5
    dom_id: '#swagger-ui',
6
    presets: [
7
      SwaggerUIBundle.presets.apis,
8
      SwaggerUIBundle.SwaggerUIStandalonePreset
9
    ],
10
    layout: "StandaloneLayout"
11
  })

SwaggerUIBundle 等同于 SwaggerUI。

Docker

您可以直接从 Docker Hub 拉取 swagger-ui 的预构建 docker 镜像

1
docker pull swaggerapi/swagger-ui
2
docker run -p 80:8080 swaggerapi/swagger-ui

将启动 nginx，Swagger UI 在端口 80 上运行。

或者您可以在主机上提供您自己的 swagger.json

1
docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

您还可以提供外部主机上 swagger.json 的 URL

1
docker run -p 80:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json swaggerapi/swagger-ui

可以通过指定 BASE_URL 环境变量来更改 Web 应用程序的基本 URL

1
docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

这将在 /swagger 而不是 / 上提供 Swagger UI。

您可以通过 PORT 变量指定访问应用程序的不同端口，默认值为 8080。

1
docker run -p 80:80 -e PORT=80 swaggerapi/swagger-ui

您可以通过 PORT_IPV6 变量指定 IPv6 端口。默认情况下，未设置 IPv6 端口。

1
docker run -p 80:80 -e PORT_IPV6=8080 swaggerapi/swagger-ui

您可以通过 EMBEDDING 变量允许/禁止嵌入。默认情况下，禁用嵌入。

1
docker run -p 80:80 -e EMBEDDING=true swaggerapi/swagger-ui

有关通过 Docker 镜像控制 Swagger UI 的更多信息，请参阅配置文档的 Docker 部分。

unpkg

您可以使用 unpkg 的接口将 Swagger UI 的代码直接嵌入到您的 HTML 中

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
  <meta charset="utf-8" />
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
  <meta name="description" content="SwaggerUI" />
7
  <title>SwaggerUI</title>
8
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
9
</head>
10
<body>
11
<div id="swagger-ui"></div>
12
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
13
<script>
14
  window.onload = () => {
15
    window.ui = SwaggerUIBundle({
16
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
17
      dom_id: '#swagger-ui',
18
    });
19
  };
20
</script>
21
</body>
22
</html>

使用 StandalonePreset 也会渲染 TopBar 和 ValidatorBadge。

1
<!DOCTYPE html>
2
<html lang="en">
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1" />
6
    <meta name="description" content="SwaggerUI" />
7
    <title>SwaggerUI</title>
8
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
9
  </head>
10
  <body>
11
  <div id="swagger-ui"></div>
12
  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
13
  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js" crossorigin></script>
14
  <script>
15
    window.onload = () => {
16
      window.ui = SwaggerUIBundle({
17
        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
18
        dom_id: '#swagger-ui',
19
        presets: [
20
          SwaggerUIBundle.presets.apis,
21
          SwaggerUIStandalonePreset
22
        ],
23
        layout: "StandaloneLayout",
24
      });
25
    };
26
  </script>
27
  </body>
28
</html>

有关如何使用 unpkg 的更多信息，请参阅 unpkg 的主页。

没有 HTTP 或 HTML 的静态文件

一旦 swagger-ui 成功生成了 /dist 目录，您可以将其复制到您自己的文件系统并从那里托管。

普通旧的 HTML/CSS/JS（独立）

/dist 文件夹包含在静态网站或 CMS 上运行 SwaggerUI 所需的所有 HTML、CSS 和 JS 文件，而无需 NPM。

下载最新版本。
将 /dist 文件夹的内容复制到您的服务器。
在文本编辑器中打开 swagger-initializer.js，并将“https://petstore.swagger.io/v2/swagger.json”替换为您的 OpenAPI 3.0 规范的 URL。