安裝

發佈管道

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

將在連接埠 80 上使用 Swagger UI 啟動 nginx。

或者，您可以在主機上提供自己的 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 介面，直接在 HTML 中嵌入 Swagger UI 的程式碼

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。