2019」22日目の記事です)こんにちは、システムズエンジニアリングセンターのくりくりです。北海道から上京して初の猛暑を乗り越え、慣れ親しんだ冬に突入しましたが、やっぱり寒いものは寒いです。コートは欠かせませんね。前回参画したプロジェクトでは、また違ったツールを使用していました。それがSwaggerです。この記事ではSwaggerの簡単な概要と実際に使用した方法をご紹介します。最後にSwaggerとは?OpenAPI仕様に基づいて構築された一連のオープンソースのツールです。APIを記述するための標準仕様であり、yamlやjsonで記述できる。Swaggerでは可読性が高く、おしゃれなデザインの設計書が作成できます。そのため作成者以外でも探している内容がどこに記述されているか直感的に探すことができるでしょう。設計書から実際のAPIにリクエストを送りレスポンスを確認する単体テストが可能です。実際に作成するためのツールは公式から公開されています。CodegenOpenAPI仕様で定義されたAPIのスタブとクライアントSDKを生成します。できるエディターです。Swaggerを知るにはまずこれを触ると分かりやすいと思います。UIOpenAPI仕様で記述されたドキュメントをHTML形式で自動生成します。実際に書いてみたそれでは実際に書いてみましょう。今回は上記で紹介したツールではなく実際に利用した方法をご紹介します。※環境構築は省略します。Viwer(VSCodeの拡張機能)redoc-cil(yamlからHTML生成してくれるツール)手順1まずVSCodeにyamlで以下のコードを記述します。Pを押すとプレビューが見れます。このプレビューからAPIへリクエストを送ることができるため、単体テストのようなものが可能です。手順2次はyamlをhtml形式で出力してみましょう。以下のコマンドを実行してください。index.htmlするとindex.htmlというファイルが出来ていると思います。それを開くと・・・とても見やすいAPI設計書が作成できました!あとは書き方さえ覚えれば可読性が高くおしゃれなAPI設計書を作ることができます!利点と欠点Swaggerの利点としては以下が挙げられます。「書いた人によって書き方が違う・・」なんてことにはなりません。Gitで差分が見れるExcelと異なりバイナリファイルではないため、Gitで差分を見ることができます。再利用性があるコンポーネントを作成することで重複する内容を何度も書かず再利用することができます。今回ご紹介したコードの76行目以降に記述されています。欠点としては以下が挙げられます。学習コストが高いOpenAPI仕様の書き方から学ばなければならないため実際にプロジェクトで使用するまでには時間が掛かってしまいます。最後にこれまでExcelで仕様書を書いていましたが、Markdown派だった私は初めてSwaggerを見たとき衝撃を受けました。最初は書き方がよく分からず他で作るより時間が掛かってしまいましたが、慣れてくると一つのAPIを書くのにそこまで時間が掛からなくなりました。