コンテンツにスキップ

インストール

配布チャネル

NPM レジストリ

npm には、swagger-ui、swagger-ui-dist、swagger-ui-react の 3 つのモジュールを公開しています。

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 Getting Started のサンプルを参照してください。

対照的に、swagger-ui-dist は、クライアントに提供するアセットを必要とするサーバーサイドプロジェクトを対象としています。このモジュールは、インポートされると、swagger-ui-dist モジュールがインストールされている絶対ファイルシステムパスを返す absolutePath ヘルパー関数を含みます。

注: ツールで可能な場合は swagger-ui の使用をお勧めします。swagger-ui-dist を使用すると、より多くのコードがネットワーク経由で送信されることになります。

モジュールの内容は、Git リポジトリにある dist フォルダーを反映しています。最も有用なファイルは swagger-ui-bundle.js で、これは Swagger UI が実行に必要なすべてのコードを 1 つのファイルにまとめたビルドです。このフォルダーには 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

swagger-ui のビルド済み Docker イメージは、docker.swagger.io から直接プルできます。

ターミナルウィンドウ
1
docker pull docker.swagger.io/swaggerapi/swagger-ui
2
docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui

Swagger UI を使用して nginx をポート 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

Web アプリケーションのベース URL は、BASE_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

IPv6 ポートは PORT_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 を制御する方法の詳細については、Configuration ドキュメントの 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 フォルダーには、NPM を必要とせずに、静的 Web サイトまたは CMS で SwaggerUI を実行するために必要なすべての HTML、CSS、および JS ファイルが含まれています。

  1. 最新リリースをダウンロードします。
  2. /dist フォルダーの内容をサーバーにコピーします。
  3. テキストエディターで swagger-initializer.js を開き、「https://petstore.swagger.io/v2/swagger.json」を OpenAPI 3.0 仕様の URL に置き換えます。
© . This site is unofficial and not affiliated with Swagger.