API環境を使うときの仕様ドキュメントでとても便利なSwagger。
こちらをCeontOS7にインストールしてみます。
実行環境ではnode.jsを使うのでそちらのインストールから実施です。
Swagger環境のインストール
インストールは以下で行います。
|
1 2 3 4 |
# yum -y install nodejs # npm install -g swagger |
こちらでプロジェクトの作成などを実施して行きます。
プロジェクトの作成と起動
以下でプロジェクトの作成を行います。
|
1 2 3 4 5 6 7 8 9 |
# swagger project create プロジェクト名 ? Framework? connect ❯ express hapi restify sails |
フレームワークでは「express」を選択しています。
プロジェクトの作成後にプロジェクトディレクトリに移動します。
|
1 2 3 |
# cd プロジェクト名/ |
次に上記で作成したプロジェクトの起動を行います。
|
1 2 3 4 5 6 7 8 9 |
# swagger project start Starting: /tmp/プロジェクト名/app.js... project started here: http://localhost:10010/ project will restart on changes. to restart at any time, enter `rs` try this: curl http://127.0.0.1:10010/hello?name=Scott |
「http://127.0.0.1:10010/hello?name=Scott」で接続しなさいと出てきました。
接続すると以下のような表示になります。
BindIPなどはないので以下のURLでアクセスできます。
http://XXX.XXX.XXX.XXX:10010/hello?name=Scott
firewall-cmdで制御している時などは以下にてポートも開けます。
|
1 2 3 4 |
# firewall-cmd --add-port=10010/tcp # firewall-cmd --permanent --add-port=10010/tcp |
ポートは「app.js」の以下の部分で設定していますので起動を「env PORT=XXXX swagger project start」とするかapp.jsの該当箇所を変更します。
|
1 2 3 |
var port = process.env.PORT || 10010; |
アプリについて
上記ではhelloというAPIにScottという引数を渡しています。
こちらは「api/swagger/swagger.yaml」に記載があります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
paths: /hello: # binds a127 app logic to a route x-swagger-router-controller: hello_world get: description: Returns 'Hello' to the caller # used as the method name of the controller operationId: hello parameters: - name: name in: query description: The name of the person to whom to say hello required: false type: string responses: "200": description: Success schema: # a pointer to a definition $ref: "#/definitions/HelloWorldResponse" # responses may fall through to errors default: description: Error schema: $ref: "#/definitions/ErrorResponse" |
こちらの「/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のインストール配下で行います。
|
1 2 3 |
# npm install cors --save |
インストール後にapp.jsを編集します。
|
1 2 3 4 5 6 7 |
module.exports = app; // for testing // 以下を追加 var cors = require('cors'); app.use(cors()); |
ファイルを保存すると設定の読み直しを行ってくれます。
次に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を起動することができます。
|
1 2 3 4 5 6 7 |
var port = process.env.PORT || 10010; // 以下の1行を追加 app.use(swaggerExpress.runner.swaggerTools.swaggerUi()); app.listen(port); |
こちらで起動をしなおすとHTMLでのドキュメントの確認ができます。
以下のURLでSwagger-UIの確認ができます。
http://XXX.XXX.XXX.XXX:10010/docs/
Swagger-Editorの方でファイルを編集してyamlを作成していくと効率的にドキュメントファイルが作れると思います。
今回はインストールでしたのでこの辺で。
このブログは株式会社CoLabMixによる技術ブログです。
GCP、AWSなどでのインフラ構築・運用や、クローリング・分析・検索などを主体とした開発を行なっています。
Ruby on RailsやDjango、Pythonなどの開発依頼などお気軽にお声がけください。
開発パートナーを増やしたいという企業と積極的に繋がっていきたいです。
