Swagger UI の使い方

今回は「Swagger UI の使い方」についてまとめます。

Swagger UI とは
基本的な使い方
Node.js + Express サーバー上に展開
初期表示のカスタマイズ
- 自身のAPI仕様を表示
- ヘッダーを非表示
（おまけ）最終的な構成

Swagger UI とは

Swagger UI とは「OpenAPI Specificatioinに従って記述されたAPI仕様書をWebページ上で見やすく表示するツール」です。 Swagger Editor, Codegen とともによく使われるツールになります。

Swagger UI は単純なWebアプリなので仕組みさえわかれば使い方は簡単です。

基本的な使い方

Swagger UI はHTML+JavaScriptで作られた単純なSPA（Single Page Application）です。そのため、使い方は必要なソースコード（HTML + JavaScript など）を Webサーバー上に静的コンテンツとして展開できれば利用ができます。

以下では「必要なソースコードのダウンロード」と「ソースコードの展開先」について順に説明します。実際の「使い方」はこれらの組み合わせになるので何パターンかやり方はあると思います。

ソースコードの取得方法

必要となるものは GitHub （ swagger-api / swagger-ui ）上に展開されている dist 以下に存在するファイル群です。その取得方法は以下の2通りがあります。

GitHub 上のソースコードを直接ダウンロード

GitHub swagger-api / swagger-ui
npm からダウンロード
```
npm install swagger-ui-dist
```

ソースコードの展開先

いわゆる一般的なWebサーバーに展開します。展開先はWebサーバーであればどこでも良いので以下のようなものが考えられます。もちろん、Docker上に存在するWebサーバーでもOKです。

IIS
NGINX
Apache httpd
Node.js

Node.js + Express サーバー上に展開

今回は npm でソースコードを取得し、Node.js + Express 上に静的コンテンツとして展開する方法で環境構築してみます。やや実装が入るので少し面倒ですが… Swagger UI の基本的な動作が理解できます。

まずはサーバー側の実装を行っていきます。 …といっても静的コンテンツとして展開するだけなので、特に難しい実装はありません。単純に右から左へ転送するサーバーを作るだけです。

プロジェクト作成

以下のコマンドを実行して package.json を作成します。
```
npm init
```

package.json を修正

script にある不要なテストコマンドを削除し、起動用コマンドを追加します。

/package.json

...(省略)...
  "scripts": {
    // "test": "echo \"Error: no test specified\" && exit 1"  // ←削除
    "start": "node index.js"                                  // ←追加
  },
...(省略)...

必要なモジュールを追加

必要となる express、 swagger-ui-dist を追加します。
```
npm install express swagger-ui-dist
```
サーバーサイド実装

index.jsにメインの処理を記述します。 /specフォルダを追加しているのは、この後このフォルダに展開したい OpenAPI Specification を配置するためです。

/index.js
```
var { absolutePath } = require("swagger-ui-dist");
var express = require("express");
var app = express();

app.use(express.static(absolutePath()));

app.listen(3000);
```

サーバー起動は package.json にスクリプト追加しているのでプロンプト起動して npm start だけです。

サーバー起動

新しくコマンドプロンプトを起動して以下のコマンドを実行します。
```
npm start
```

サーバー起動すると localhost:3000 で待ち受けているので適当なブラウザでアクセスします。正しく準備できていれば以下のようなSinglePageApplication画面が表示されます。

初期表示のカスタマイズ

デフォルトのままだと "Petstore API" が表示されます。ヘッダーに仕様書へのURLを記述して「Explore」を行えばもちろん任意の仕様書を表示できますが… 通常利用で考えると「自分の記述しているAPI仕様書」をいきなり表示してほしいものです。

以下では「自分が記述しているAPI仕様書」をいきなり表示できるようなカスタマイズを行っていきます。冒頭にも記載しましたが、Swagger UI は SPA(Single Page Application) ですので swagger-ui-dist 以下に存在する index.html を直接編集することでカスタマイズを行っていきます。

SwaggerUIBundleに渡されるオプション url を書き換えることで初期表示を切り替えることができます。ただし、自身が記述しているAPI仕様書もWeb上で公開する必要があるので、こちらもあわせて行います。

今回は /spec フォルダを作成し、このフォルダ以下に openapi.yaml を配置、これを初期表示できるようにします。

サーバーサイド実装の修正

index.jsに /spec 以下に配置された静的コンテンツ配信を行うコードを追記します。

/index.js

var path =require("path");
var { absolutePath } = require("swagger-ui-dist");
var express = require("express");
var app = express();

app.use("/spec", express.static(path.join(__dirname, "./spec")));
app.use(express.static(absolutePath()));

app.listen(3000);

OpenAPI Specification を配置

表示したいOpenAPI Specificationファイルを以下のフォルダへ配置します。
```
/ROOT
 └ /spec
     └ openapi.yaml      ←表示させたいOpenAPI Specification
```

初期表示設定の修正

swagger-ui-distのindex.htmlに記述されている初期表示設定を自身のAPI仕様書が表示されるよう修正します。修正箇所は url パラメータの値部分になります。

/node_modules/swagger-ui-dist/index.html

...(省略)...
    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        // url: "https://petstore.swagger.io/v2/swagger.json", // ←削除
        url: "/spec/openapi.yaml",                             // ←追加
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>
...(省略)...

ここまで実装したらサーバーを起動してみます。問題なければ以下のように初期表示されるはずです。

ここまでくると、ヘッダーが不要なことに気づきます… CSSを編集してヘッダーが表示されないように修正します。

ヘッダー非表示になるよう修正

swagger-ui-distのindex.htmlにヘッダー（.topbar）が非表示にされるようなCSSを追記します。

/node_modules/swagger-ui-dist/index.html

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>

...(省略)...

    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }

      .topbar
      {
        display: none;
      }
    </style>

...(省略)...

ここまで実装したら再度サーバーを起動してみます。問題なければ以下のように初期表示されるはずです。

（おまけ）最終的な構成

作成完了した際のフォルダ/ファイルは以下のようになっています。追加、修正したのはハイライト部分です。

/ROOT
│  index.js
│  package.json
│  
├─node_modules
│  │          
│  │          
│ ...(省略)...
│  │      
│  ├─swagger-ui-dist
│  │      absolute-path.js
│  │      favicon-16x16.png
│  │      favicon-32x32.png
│  │      index.html
│  │      index.js
│  │      oauth2-redirect.html
│  │      package.json
│  │      README.md
│  │      swagger-ui-bundle.js
│  │      swagger-ui-bundle.js.map
│  │      swagger-ui-standalone-preset.js
│  │      swagger-ui-standalone-preset.js.map
│  │      swagger-ui.css
│  │      swagger-ui.css.map
│  │      swagger-ui.js
│  │      swagger-ui.js.map
│  │      
│ ...(省略)...
│
│
└─spec
        openapi.yaml

/index.js

var path =require("path");
var { absolutePath } = require("swagger-ui-dist");
var express = require("express");
var app = express();

app.use("/spec", express.static(path.join(__dirname, "./spec")));
app.use(express.static(absolutePath()));

app.listen(3000);

/package.json

{
  "name": "sample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "author": "",
  "license": "MIT",
  "dependencies": {
    "express": "^4.17.1",
    "swagger-ui-dist": "^3.25.1"
  }
}

/node_modules/swagger-ui-dist/index.html

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">

...(省略)...

    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }

      .topbar
      {
        display: none;
      }
    </style>

...(省略)...

    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "/spec/openapi.yaml",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>

...(省略)...

</html>

今回は「Swagger UI の使い方」についてまとめました。参考になったでしょうか？本記事がお役に立っていると嬉しいです！！

最後に… このブログに興味を持っていただけた方は、ぜひ「Facebookページにいいね！」または「Twitter のフォロー」お願いします！！

galife

Swagger UI の使い方

Swagger UI とは

基本的な使い方

Node.js + Express サーバー上に展開

サーバーの実装

サーバーの起動

動作確認

初期表示のカスタマイズ

自身のAPI仕様を表示

ヘッダーを非表示

（おまけ）最終的な構成

Labels

Archives

Pages

Contact