Hello Ecomott!
はじめまして、クラウドソリューション開発部 伊藤 と申します。
今年4月に札幌に移住・入社して、早4ヵ月。北国のイメージとは全く異なる
札幌の夏の暑さの洗礼を受ける日々を送っています。暑さから逃げてきたのに東京と変わらないのでは？
この度、Tech Blog執筆のお鉢が回ってきたということで、弊社では珍しい（？）
文系出身エンジニアという特徴を活かして、気楽に読める記事をお届けできればと思います。
というわけで、今回は、現在API仕様書のリプレイス作業で絶賛活用中のSwagger について、
SwaggerによるAPI仕様書ドキュメントの作成と、「なぜSwaggerを使うべきなのか？」という観点に
フォーカスし、Swaggerというワードを知らない、あるいは聞き覚えがあるといったレベルの
初心者向けにかみ砕いて概要をお届けする記事となります。
企業のTechBlogを欠かさずチェックされているような読者諸兄には釈迦に説法もいいところでしょうが、どうぞお付き合いください。
Swaggerとは
まずは私自身、作業を振られた際に抱いた疑問。
ーーSwaggerって何？ という話。
せっかくなのでChat GPTにも聞いてみた。
RESTful APIを定義するフォーマットであるOpenAPI仕様に基づき構築された、API仕様書を記述・作成するための一連のオープンソースツールの総称。
・・・・・・とのこと。一応調べてみた結果、概要としてはこの解釈で間違いは無さそう。
元々はREST APIの定義仕様（現：OpenAPI仕様）そのものを指していたところ、色々あってOpenAPIが定義仕様になったため、現在ではSwaggerは「OpenAPI仕様に則り構築されたツール群」を指す言葉となっているようですね。
私の作業時もそうでしたが、「Swagger 記法」といったワードで検索してみて、思ったよりヒットしなくて困惑する初心者の混乱の元は、こうした経緯が遠因となっているのかもしれませんね。
箸休めに全くの余談ですが、文系らしい寄り道をば。
「Swagger」とは「偉そう」とか「イキリ散らした」とかそんな悪口に近い意味合いだったような。
古英語由来だったはずですが、アメリカでは尖った魅力を形容するスラングだとか。本ツール名の由来として使われているのはそちらでしょうね。
「偉そう」にするだけの実力を秘めた、とても便利なツールであるという自負を窺わせる……
ような気もする、いかにも欧米的なシニカルさが光るユーモアセンスですね。
閑話休題。
話を戻すと、ややこしい背景はさておき、要は
「SwaggerはAPI仕様書を記述するための便利ツール」
である、という話になります。
なぜSwaggerを使うべきなのか？
直近でExcelで作成・管理されていたAPI仕様書のSwagger化する作業を担当した、というのが
今回、Swaggerをブログの題材として取り上げることにした経緯というのは最初に述べた通りですね。
私が担当した業務でもそうであったように、日本においてはまだまだAPI仕様書はExcelで作成するのが主流、という場面も多いのではないでしょうか。
⼀から仕様を書き起こすならまだしも、⼀度Excelで作成した仕様書をわざわざSwaggerで
作り直すのか、という感想をお持ちの読者諸兄もいらっしゃることでしょう。気持ちはわかる
Swaggerで仕様書を起こすのはいいとして、新しくAPIを開発した際にそうすればいいだけの話では？
なんで改修したわけでもないのに一度作った仕様書を作り直す必要があるのか？と。
そんな懐疑的な考えをお持ちの読者諸兄のために、SwaggerでAPI仕様を書き起こすメリットについてまとめてみました。
有用性その１．APIの仕様書を簡単に作成できる。
わかりやすい形で体感できる、最も大きなメリットがこちら。
Swaggerでは、「Swagger Spec」というOpenAPI仕様に準拠したフォーマットにより、
JSONまたはYAML形式で簡単にAPI仕様書を書き起こすことができます。
これにより、最低限の記述で非常にわかりやすいドキュメントを生成してくれるのです。
独特な記法で慣れは必要ですが、最小限の記述でAPIのリソース、メソッド、パラメータ、
スキーマなどを簡単かつ正確に記述することができるよう工夫が凝らされています。
そういうわけで実際に書いてみた結果がこちら。
今回のサンプルは、Open API仕様の最小限の構成要素で記述した、
シンプルなAPIの仕様書になります。必要な記述は最低限これだけ。
【基本記法メモ】
openapi：仕様書が準拠するOpenAPIのバージョン
info: APIの基本情報を記載する。
・title：APIの名称を記載
・description：APIの概要
・version：APIのバージョンtags：API仕様ドキュメント内で使用されるタグのリストを記載する目次のようなもの。
※複数設定可能servers：APIの紐づくサーバーのURLを記載する。
※本番/ステージング等、複数のサーバーのURLを記載することも可能
paths：APIのエンドポイントを記載する。
・APIパス(例：/ecomott/tecblog:)：エンドポイントのパスを記載する。
・httpメソッド：GET/POST/DELETEなど
・summary：エンドポイントの概要欄
・description：エンドポイントの詳細説明欄
・tags：エンドポイントに紐づけられているタグ・parameters：リクエストパラメータ
・name：パラメータ名
・in：query/ header/ path/ formData/ bodyのいずれか適切なものを指定
・description：パラメータの説明
・required：必須パラメータ判定（True/False）
・schema：パラメータのスキーマ定義・responses：応答されるレスポンスの定義
・レスポンスコード（例：200：）
・description：レスポンスの説明
・content:応答されるレスポンスのメディアタイプ（例：application/json）
・schema：レスポンスボディのスキーマ定義。
Componentsに記載のschemaと紐づけて記載される。
・headers：レスポンスヘッダー
・example：レスポンス例（特定のレスポンス例を明示したい場合に使用）。
※「examples」にすることで複数の例を掲示することもできる。
components：APIで使用するスキーマ定義をまとめて記載する。
・schemas:スキーマ
・スキーマ名（例：response_dummy:）： スキーマ定義を記載する対象
・description：概要を記載
・type：データ型（string/number/integer/boolean/array/file）
・format：詳細なデータ型
・example：例となる値を明示する場合
Swagger Specの記法に則り記述することで、きわめて簡潔に、手早く、そして正確にAPI仕様書を作成できてしまうのです。
API仕様書の作成に慣れているわけでもない筆者でも、直感的にどこをどう編集すればいいかわかってしまう。
世界共通の仕様で記述するため、職場のローカルルール的な記法に惑わされることもない。
なるほど、わざわざExcel管理の仕様書から刷新したい理由が見えてきたような気もしますね。
とはいえ、簡単に記述できるのはいいとして、
そもそもyaml/jsonファイルだけでは「API仕様書」としては不十分では？
そもそもyamlファイルだけ見てもAPI仕様書として正しく記述できているのかわからないのでは？
そう考えた鋭いあなたに朗報です。続いてはそちらの懸念についての内容となります。
有用性その2．APIのドキュメントを自動生成できる。
Swaggerの主要ツールのひとつ、Swagger UIでは、Open API仕様に準拠して作成された
json/yamlファイルからHTML形式やMaerkdown形式のドキュメントを自動生成することができます。
つまり、yamlファイルを編集＝書きたい要点さえ記述してしまえば、あとはSwaggerが
ドキュメントとして良しなにまとめてくれるのです。
ドキュメントは上記の通り、プレーンで癖のないデザインで生成されます。
このような自動生成苦悩の存在により、仕様書ドキュメントの体裁や見栄えに
悩まされることもなければ、プロジェクトを去った先人の遺した意味深な記述の謎を解明するために
必要以上に頭を捻る必要もない。
そしてなにより、yamlファイルから自動生成してくれることで、記述内容の正確さも
担保されることになる。仕様書作成の手間をひと手間もふた手間も減らしてくれるわけですね。
Swaggerを記述するためのエディタツールである「Swagger Editor」にも「Swagger UI」が組み込まれており、エディタの右半分にHTMLプレビューとして、編集中のファイルから生成されるAPI仕様書を表示させてくれるため、API仕様書ドキュメントとしての完成形をリアルタイムで確認しながらコードを記述できる非常に有用な機能となっています。
ちなみに、公式ツールの「Swagger Editor」はブラウザで動作するツールであり、
導入不要で気軽に利用可能となっています。
（https://editor.swagger.io/?_ga=2.12648631.1689141289.1688542763-1645080877.1687918588）
とはいえ、今回のAPI仕様書のSwagger化は業務の範疇。
今回は上記画像のように、Vscodeの拡張機能である
サードパーティツールの「Swagger Viewer」を利用して作業を行いました。
もっとも、サードパーティ製のツールとはいえ、機能的には公式の「Swagger Editor」と
大きく変わるところはないはず。
むしろ動作が軽く、コードを編集してからビューに反映されるまでのタイムラグが少ない分、
使いやすさすら感じたのでこちらもオススメしたいところです。
Vscodeの拡張ツールなので導入は簡単、「拡張機能」から下記の「Swagger Viewer」を
インストールするだけ。
Vscodeでyamlファイルを編集する場合は、併せて「YAML」の拡張機能をインストールしておくと、
OpenAIP仕様のドキュメントを編集中にバリデーションチェックの支援を行ってくれるようになり、
ブラウザ版の「Swagger Editor」と殆ど同じ感覚で作業することができるため、
こちらも必須といえるでしょう。
有用性その3．APIの動作テストを簡単に行える。
Swagger UIには、yaml/jsonファイルからAPI仕様書ドキュメントを生成する以外に、
もう一つ重要な機能が備わっています。
なんとこちら、生成された仕様書ドキュメント上でAPIのリクエストを簡単に作成し、
APIのレスポンスを確認するテスト機能が組み込まれているのです。
リクエスト内容とそれに応じたサーバーレスポンス結果を仕様書上で
生成・表示されることで、簡易的なAPI動作テストを行うことができます。
こうした特徴は、これまでのExcel等での管理との明確な差別化点といえるでしょう。
今回は実際に試せていないため、詳細な掲載はしないものの、
より詳細なテストを行うことができるSwaggerツールもサードパーティ含め
多く存在しており、そうしたツールを併せて運用することで、よりAPI開発・管理を
効率的に進めることができます。
このように、SwaggerではAPI仕様書ドキュメントを作成するための、
他にはない有用な機能をいくつも備えているのです。
Swaggerを使ってみて
今回、業務都合でSwaggerのSの字すら知らない状態から初めてAPI仕様書を作成しての
率直な印象としては以下の通り。
１．OpenAPIの独特の記法に慣れるまで（時間的・労力的に）学習コストが掛かる
上述のように、SwaggerではOpenAPI仕様に準拠した形式でドキュメントが作成されます。
そのため、記述に当たっては少なからず制約もあり、Swaggerツール使用経験が無い場合は、
OpenAPI仕様の記法に習熟するまでの学習コストもそれなりには掛かってしまうかもしれません。
Excel等での仕様書フォーマット等が確立されている現場の場合は、仕様書作成の手軽さ、
簡単さという面では然程の恩恵は感じられないかもしれない……というのが筆者の正直な印象です。
基本的に人間の大多数は変化を嫌う生き物なわけで、API仕様書の作成・管理に習熟しているなら、
慣れた手段からわざわざ乗り換える程のメリットは感じられないかもしれないですね。
既存仕様書のOpenAPI仕様ドキュメントへの置き換えの際の導入にあたっては、こうした学習コストをどれほど許容できるか、という問題が最初の壁として立ちはだかってきそうです。
２．OpenAPI仕様に慣れさえすればむしろ手軽に仕様書ドキュメントを作成できる。
ゼロベースからAPI仕様書を書き起こす、規格がバラバラの個々で管理されていた仕様書を
纏めたい……等といった場面では、融通の利かなさともいえるOpenAPI仕様の規格化された記法や
決まりきったレイアウトなどが、
「作業者は必要な情報を必要な箇所に最低限の記述を行うだけで、ドキュメント作成のローカルルールや仕様書のレイアウト、デザイン等を考慮する必要はほとんど無い」
という明確なメリットに転化されることになります。
今回の業務では、まさにこうした理由により、Swaggerの恩恵を感じることができました。
３．ドキュメントの保守・管理は圧倒的にSwaggerが手軽で楽
ExcelなどでAPI仕様書の改訂を行う場合、改訂内容だけでなく仕様書としての体裁まで
チェックする必要があったり、ドキュメントのボリューム次第では
「そもそもどこを修正すればいいのかわかりにくい」
といったドキュメント保守上の問題は常に付きまとうことでしょう。
また、ドキュメント作成ルールやフォーマットが確立されていない場合などでは、
「どう修正すれば正しい状態になるか」「今回の改訂でどこまで修正されたか」
などといった観点からドキュメントの保守・管理面で複雑化し、
ドキュメント改訂作業を割り振られがちなプロジェクトに参画して日が浅い作業者に
初見殺しを行ったり、仕様書起草者が去った現場で形骸化したりといった
「ありがちな問題」を引き起こしたりすることも考えられます。
Swaggerが有するバージョン管理やタグによる分類といった機能、バリデーションチェック機能は、
そうしたドキュメントの保守・管理上の問題に対する特効薬になってくれるかもしれません。
おわりに
以上、しばらくの間はSwaggerと付き合う都合上、コイツを好きにならなければ
ならない……ということで、API仕様作成におけるSwagggerの有用性について、
つらつらと再考するという内容でした。
今回、業務で始めて触れてみて実感したOpenAPI(Swagger)の最大の問題は、
何より日本語リファレンスの少なさ故に、とにかく記法や活用方法についての情報が少ない、
ということでした。
基礎的な記法についての情報は見つかっても、少し応用的、実践的な内容に踏み込むと
途端に有用な情報が見つからなくなる……というように、よく言えば研究の余地がある、
悪く言えば定着しきれていない、そんなツールであるSwaggerですが、
掘り下げれば掘り下げるほど、まだまだあまり知られていない便利な機能や
優れた記法が隠れていることがわかる、中々に味があるスルメ系ツールであるということが
わかってきました。
折角長い付き合いになる以上は、使っていく中で判明していくであろうSwaggerの便利な機能や
隠れた記法などの、検索しても辿り着きにくいナレッジについて、少しずつでも連携していくことで、
Swaggerを本当の意味で使いやすく、便利なツールにしていきたいところ。
読者諸兄も是非、Swaggerに触れてみて、この気難しいツールが秘めた可能性を
どんどん掘り下げてみませんか？
それではまた！
