『REST入門』Swagger UIのインストールとIISでAPI仕様書を公開(Windows )

OpenAPI(Swagger) Swagger

ローカル環境でSwagger UIを利用するためのインストール方法と、Swagger または OpenAPI Specification に沿って記述されたAPI仕様書をIISで公開するまでを解説していきます。
こちらはWindows10で環境構築した際の記事になります。

Swagger UIのクローンを作成

以下のサイトにアクセスしてGitHubからSwagger UIのクローンを作成していきます。

https://swagger.io/tools/swagger-ui/download/

「Download」>「Clone or download」とクリックし、「URI」のクリップボードをとります。

SwaggerUIのインストールとIISで公開01

SwaggerUIのインストールとIISで公開02

 

コマンドプロンプトにクリップボードの内容を貼り付けて実行します。

SwaggerUIのインストールとIISで公開03

 

Swagger UIをインストール

先ほどのcloneコマンドを実行したディレクトリに「swagger-ui」ディレクトリが作成されます。
Swagger UIのクローンを作成したディレクトリに移動して、以下のコマンドを実行します。
これによりpackage.jsonで管理されたパッケージがインストールされます。

SwaggerUIのインストールとIISで公開04

 

Swagger UIのビルド

インストールが完了したら次はビルドを行います。これによりpackage.jsonのscriptsフィールドに記述されたbuildタスクが実行され、プロジェクトのビルドを行います。

SwaggerUIのインストールとIISで公開05

※Node.jsをインストールすることでnpmもインストールされコマンドを利用できるようになります。

以下の記事にインストール方法が記載されているので参考にしてください。

npmとは|Node.js(npm)をインストール(Windows)
npmでパッケージのインストールを行いたく、Node.jsをインストールしたので、npmとは何かとインストール手順を記事にまとめます。環境はWindows10にまります。

 

ビルドが完了したら、「dist」ディレクトリにある、「index.html」をブラウズで開くとSwagger UIが表示できることが確認できます。

SwaggerUIのインストールとIISで公開06

 

Swagger UIをWebサーバーで共有して利用

ローカルまたはWebサーバーの任意のパスに次の1つをコピーします。

・distフォルダ

SwaggerUIのインストールとIISで公開07

 

この状態で、「dist」ディレクトリ内の「index.html」をブラウザで開くことでSwagger UIが表示できることが確認できます。

SwaggerUIのインストールとIISで公開08

 

IISでWebサイトを構築することで共有してSwagger UIを利用できます。

SwaggerUIのインストールとIISで公開09

IISでの公開方法は以下を参考にして下さい。

IISでサイトを構築する(Windows10)
ここでは、Windows10の環境にIISをインストールして、サイトを構築する方法を記載します。

 

デフォルトで読み込むAPI仕様のファイルを指定する

初期の状態ではSwagger UIを起動するとサンプルである petstore のAPI仕様書を取り込むようになっています。

これを任意のAPI仕様書を取り込むように変更してみましょう。

変更は「dist」ディレクトリにあるindex.htmlの42行目の一行を変更するだけになります。

「index.html」(デフォルト)

今回はこの記事で用意したswagger-uiというサイトの「dist」ディレクトリにopenapi.jsonを用意して、こちらを参照するように変更してみます。

変更は以下のようになります。

「index.html」(任意のURLに変更)

以上です。もう一度アクセスしてみましょう。

SwaggerUIのインストールとIISで公開10

成功しました。

同じように、openapi.yamlでも試してみましたが正常に表示できました。

SwaggerUIのインストールとIISで公開11

 

YAML、JSONファイルを指定してエラーが発生した場合の解決方法

YAMLやJSONファイルを指定すると、以下のエラーが発生することがあります。

SwaggerUIのインストールとIISで公開12

参照先が正しく、拡張子も正しい場合は、MIMEの関連付けがされていない場合があります。

この問題はweb.configまたはIISで拡張子を関連付けることで解決できます。

ここではweb.configの設定方法を解説します。なぜかというと、複数サーバーに展開した場合にIISの設定に依存しなくなるため、設定もれによる同じ問題が発生しなくなるからです。

web.configは「dist」ディレクトりにあるので以下のコードを追加してください。追加できたらブラウザすると正しく読み込めることが確認できます。

<system.webServer>
  <staticContent>
    <remove fileExtension=".yaml" />
    <mimeMap fileExtension=".yaml" mimeType="application/yaml" />
  </staticContent>
</system.webServer>

また、IISの設定からも拡張子を関連付けしたい場合は以下の記事を参考に変更してみてください。

◇作成中です待っててねm(_ _)m◇

タイトルとURLをコピーしました