CentOS7にSwaggerのインストール

API環境を使うときの仕様ドキュメントでとても便利なSwagger。

こちらをCeontOS7にインストールしてみます。

実行環境ではnode.jsを使うのでそちらのインストールから実施です。

 

Swagger環境のインストール

インストールは以下で行います。

こちらでプロジェクトの作成などを実施して行きます。

 

プロジェクトの作成と起動

以下でプロジェクトの作成を行います。

フレームワークでは「express」を選択しています。

プロジェクトの作成後にプロジェクトディレクトリに移動します。

 

次に上記で作成したプロジェクトの起動を行います。

 

「http://127.0.0.1:10010/hello?name=Scott」で接続しなさいと出てきました。

接続すると以下のような表示になります。

 

BindIPなどはないので以下のURLでアクセスできます。

http://XXX.XXX.XXX.XXX:10010/hello?name=Scott

firewall-cmdで制御している時などは以下にてポートも開けます。

 

ポートは「app.js」の以下の部分で設定していますので起動を「env PORT=XXXX swagger project start」とするかapp.jsの該当箇所を変更します。

 

 

アプリについて

上記ではhelloというAPIにScottという引数を渡しています。

こちらは「api/swagger/swagger.yaml」に記載があります。

 

こちらの「/hello」というエンドポイント配下の「x-swagger-router-controller: hello_world」部分。

こちらがこのエンドポイントのコントローラーとなります。

「api/controllers/hello_world.js」というファイルで記載されたファイルで動きを設定しています。

 

API仕様のドキュメントを作成する環境構築

Swaggerでは表示を編集するSwagger-EditorとHTMLで表示してくれるSwagger-UIというツールが存在します。

直接「api/swagger/swagger.yaml」などのファイルを編集しても良いのですがUI環境を整えての方がやりやすいのでこちらを実施します。

このツールを使って編集を行うためにサーバ側のCORS対応を行う必要があります。

npmのインストール配下で行います。

 

インストール後にapp.jsを編集します。

 

ファイルを保存すると設定の読み直しを行ってくれます。

次にEditorファイルのダウンロードを行います。

以下のgitプロジェクトをダウンロードして、ローカルでindex.htmlを開くと編集が行えます。(Swagger-UIはDistフォルダ以下)

・Swagger-Editor

https://github.com/swagger-api/swagger-editor

 

・Swagger-UI

https://github.com/swagger-api/swagger-ui

 

以下のような形でローカルでEditorを使用できます。

file:///Users/User/Desktop/swagger-editor-master/index.html?url=http://XXX.XXX.XXX.XXX:10010/swagger

file:///Users/User/Desktop/swagger-ui-master/dist/index.html?url=http://XXX.XXX.XXX.XXX:10010/swagger

それぞれ画面は以下のようになります。

・Swagger-Editor

 

・Swagger-UI

 

 

サーバーサイドでSwagger-UIの起動

ローカルでだけHTMLの管理をしても大変ですのでServerにも追加します。

app.jsに追加することでサーバー側でもSwagger-UIを起動することができます。

こちらで起動をしなおすとHTMLでのドキュメントの確認ができます。

以下のURLでSwagger-UIの確認ができます。

http://XXX.XXX.XXX.XXX:10010/docs/

 

Swagger-Editorの方でファイルを編集してyamlを作成していくと効率的にドキュメントファイルが作れると思います。

今回はインストールでしたのでこの辺で。