Swaggerの初心者向け使い方紹介
面倒な前置きは一旦省きましょう！
ここではSwaggerの説明をしますが、こんな人をターゲットにしています。
- Swaggerで何が出来るのかよく分かんない人
- なんだかよく分かんないけどSwagger使ってカッコイイAPIの仕様書が作りたい人
- Swagger使ってみたけど無駄に長いペットショップのサンプルにうんざりしている人
では今回も初めて行きます。
そもそもSwaggerってなにが出来るんだ
Swaggerを使うとAPIの仕様書を作れます。
作ったAPIのモックサーバーが自動で作れます。
テスト用のクライアントが自動で作れます。
と、色々便利そうな機能があるのでぜひ使ってみたいと思うこと間違いなし。
Swaggerにはいくつかツールがあるのですが、とりあえずはエディターを使ってみましょう。
Swagger Editor を使ってみる
Swagger Editor は仕様書を作る為のエディターです。
Swagger Editor を使うには以下のように大体3つくらい選択肢があります。
- WEBのEditor をサクッと使う
- ローカルにインストールして使う
- エディタのプラグインで使う
1.はお手軽。Swagger Editor はWEBサービスでも提供されているのでブラウザでアクセスするだけで制限なしに利用することができます。
2.はローカルにインストールして使う方法です。業務的な関係でインターネットでの編集はちょっとという人にはいいんではないでしょうか。Docker でも専用のコンテナがあるのでインストールもそんなに難しくないです。
3.はVS Codeの様なエディタのプラグインとして使う方法です。こちらもプラグインをインストールするだけなので特に難しいことはありません。
要するにどの方法でもお手軽に使うことができるので導入は問題ないでしょう。
今回はWEBのEditorを使って行きましょう。
ペットショップのサンプルを表示させる
WEBのエディタを開くと画面左にエディタ、右には作成されたAPI仕様書が表示されています。
更新するとすぐに右の仕様書に反映され行きますのでせっかちな人も快適に使えます。
初めてWEBエディタを開くとペットショップのAPIサンプルが表示されています。
文法についてはいずれ紹介して行きます。
WEBエディタは編集した内容を自動で記録する機能がついているので何かの拍子に編集してしまうとサンプルが表示されない場合がありますので、まずは画面上部のFileタブをクリックし1番下のClear editor を選択しエディタを綺麗にしましょう。
めでたくサンプルが復活します。
モックを出力しよう
Fileタブの並びにGenerate Server、Generate Client のタブがあります。
それぞれモックサーバとモッククライアントの自動作成することができます。
選択すると様々な言語、フレームワークで作成されたモックを利用できます。
希望の言語、フレームワークを選択するとzipファイルがダウンロードされますので任意のフォルダに展開します。
展開したフォルダ内にはそれぞれREADMEファイルがあると思うので指示に従っていくとモックを利用することができます！
モックサーバにアクセスするとAPI仕様書が表示がされ、しかもその仕様書の中でリクエストのパラメータを設定して通信テストを行う事ができます。
通常、仕様書を作成しても本当にその通りに通信ができるかはサーバを作らないと分からないのですが仕様書からモックサーバがそのまま作成されるのですぐに確認できて効率が良くなります。
まとめ
今回は本当に概要だけでしたが次回以降はもう少し詳しい内容を書いて行きたいと思いますからお楽しみに！