跳到内容

安装

分发渠道

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 包含一个命名空间样式表。示例如下：

安装

您现在可以使用 npm 安装 SwaggerUI 包

终端窗口
1
 $ npm install swagger-ui
终端窗口
1
 $ npm install swagger-ui-react
终端窗口
1
 $ npm install swagger-ui-dist
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.swagger.io 拉取 Swagger UI 的预构建 docker 镜像

终端窗口
1
docker pull docker.swagger.io/swaggerapi/swagger-ui
2
docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui

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

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

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

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

终端窗口
1
docker run -p 80:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json docker.swagger.io/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 docker.swagger.io/swaggerapi/swagger-ui

这将使 Swagger UI 在 /swagger 而不是 / 提供服务。

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

终端窗口
1
docker run -p 80:80 -e PORT=80 docker.swagger.io/swaggerapi/swagger-ui

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

终端窗口
1
docker run -p 80:80 -e PORT_IPV6=8080 docker.swagger.io/swaggerapi/swagger-ui

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

终端窗口
1
docker run -p 80:80 -e EMBEDDING=true docker.swagger.io/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。

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