インストール

配布チャネル

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`に名前空間付きスタイルシートも含まれています。例：

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

SwaggerUI({
  dom_id: '#myDomId'
})

詳細は、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を次のように簡単に提供できます。

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

const app = express()

app.use(express.static(pathToSwaggerUi))

app.listen(3000)

モジュールは`SwaggerUIBundle`と`SwaggerUIStandalonePreset`もエクスポートするため、従来のnpmモジュールを処理できないJavaScriptプロジェクトにいる場合は、次のようなことができます。

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

const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  })

`SwaggerUIBundle`は`SwaggerUI`と同等です。

Docker

Docker Hubからswagger-uiの事前にビルドされたDockerイメージを直接プルできます。

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

ポート80でSwagger UIを使用してnginxを起動します。

または、ホストで独自のswagger.jsonを提供することもできます。

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

外部ホスト上のswagger.jsonへのURLを提供することもできます。

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

WebアプリケーションのベースURLは、`BASE_URL`環境変数を指定することで変更できます。

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

これにより、Swagger UIは`/`ではなく`/swagger`で提供されます。

アプリケーションにアクセスするための`PORT`変数を使用して別のポートを指定できます。デフォルトは`8080`です。

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

`PORT_IPV6`変数を使用してIPv6ポートを指定できます。デフォルトでは、IPv6ポートは設定されていません。

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

`EMBEDDING`変数を使用して、埋め込みを許可/禁止できます。デフォルトでは、埋め込みは無効になっています。

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

DockerイメージによるSwagger UIの制御の詳細については、設定ドキュメントのDockerセクションを参照してください。

unpkg

unpkgのインターフェースを使用して、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="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>

`StandalonePreset`を使用すると、`TopBar`と`ValidatorBadge`もレンダリングされます。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="SwaggerUI" />
    <title>SwaggerUI</title>
    <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
  </head>
  <body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
  <script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js" crossorigin></script>
  <script>
    window.onload = () => {
      window.ui = SwaggerUIBundle({
        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "StandaloneLayout",
      });
    };
  </script>
  </body>
</html>

unpkgの使用方法の詳細については、unpkgのメインページを参照してください。

HTTPまたはHTMLを使用しない静的ファイル

swagger-uiが`/dist`ディレクトリを正常に生成したら、これを独自のファイルシステムにコピーしてそこからホストできます。

従来のHTML / CSS / JS（スタンドアロン）

`/dist`フォルダには、NPMを必要とせずに、静的WebサイトまたはCMSでSwaggerUIを実行するために必要なすべてのHTML、CSS、JSファイルが含まれています。

最新リリースをダウンロードしてください。
`/dist`フォルダの内容をサーバーにコピーします。
テキストエディターで`swagger-initializer.js`を開き、「https://petstore.swagger.io/v2/swagger.json」をOpenAPI 3.0仕様のURLに置き換えます。