- はじめに
- Swagger（OpenAPI）とは？
- なぜ Swagger を使うのか
- Swagger の主要なツールたち
- Swaggerを使ったAPIドキュメント作成の基本ステップ
- 私が Swagger を実際に使ってみた感想
- まとめ
はじめに
はじめまして。ネットコム新人エンジニアの井手上と申します。 普段は、Webシステムの開発・保守を行っています。
Webシステム・アプリ開発に興味を持つと、Swagger という言葉を耳にする機会があるかもしれません。 私は実際にプロジェクトに配属されるまでは Swagger という単語すら聞いたことがありませんでした。
IT知識全般に言えることですが、調べてみても結局、説明や定義が難しくてわからないという方は少なくないと思います。そこで今回はこの Swagger について、IT初心者の方向けにシンプルに解説したいと思います。
Swagger（OpenAPI）とは？
※ Swagger は仕様が進化し、2016年に名前が「OpenAPI Specification (OAS)」に変更されていますが、本記事では一口に Swagger と呼ぶこととします。*1。
Swaggerとは、ひとことで言うと「APIを管理するための無料のツールセット」です。 （ツールによっては一部、有料プランを提供しているものもありますが、主要なツールは基本的に無料で提供されています。）
実際にSwagger は、世界的にも広く採用されており、Google、Microsoft、Amazonなどの企業がAPI開発に活用するなど、今日ではこういったAPI開発用のツールはもはや欠かせないものとなっています。
ただし、Swagger を理解するにはアプリケーション開発において中心的な役割を果たしているAPI（アプリケーションプログラミングインターフェース）がどんな役割を持っているのかをしっかり理解しておく必要があります。
APIとは、異なるシステムやサービスがデータや機能をやり取りするためのインターフェースであり、マイクロサービスアーキテクチャ*2やクラウドをベースとしたシステムにおいては特に不可欠です。
APIを通じて、例えば次のようなことが可能になります。
アプリケーション ⇔ サーバー間の通信
Webサービスや外部システムとのデータ連携
機能ごとのサービスの分割&管理（マイクロサービス）
APIは外部の開発者やサービスが自分たちのシステムと連携するための窓口でもあり、ビジネスの拡張性を高める役割も担います。
そこで、これらのAPIを正確に設計、ドキュメント化などして管理するために Swagger が存在するのです。
なぜ Swagger を使うのか
APIはその重要性ゆえに、正確で一貫性のある設計が求められます。APIがうまく設計されていない場合、発生しうる問題には以下のようなものがあります。
APIの使用方法が明確でないため、他の開発者やチームが誤った使い方をしてしまった
仕様に変更があった際にメンテナンスを行ったが、予期しない範囲まで修正の影響がでてしまった
テストの際に、APIの振る舞いやレスポンスが明確でないため、不具合を早期に発見&対応することができなかった
Swagger を使わずにAPIを管理する場合、Excelを使って管理するケースが考えられますが、その場合上記以外にも、すべて手動管理になってしまうということや、ドキュメントの整合性が保たれなくなるといったデメリットがあります。
これらの問題を解決するためには、APIを設計段階からしっかりと文書化し、標準化する必要があり、そういった時に役立つのが Swagger なのです。
では、Swaggerを使うと具体的にどのようなメリットがあるのでしょうか。
統一感のあるAPI仕様の定義
Swagger は、APIの設計を統一的な形式で記述するための標準フォーマットを提供します。これにより、APIのエンドポイント*3、リクエスト、レスポンス、データ型、エラーコードなどがすべて明確に定義されます。このように、API設計が文書として明示されることで、開発者間での誤解や不一致を防ぎ、一貫性のあるAPI開発が可能になります。
自動化と効率化
Swaggerを使用することで、APIドキュメントを自動生成できるため、手動でのドキュメント作成作業が省力化されます。Swagger UIやSwagger Editorなどのツールを使うと、設計したAPI仕様を基にインタラクティブなドキュメントを提供でき、開発者が実際にAPIをテストする際にも役立ちます。また、Swagger Codegenを使えば、API仕様からサーバーやクライアントのコードを自動生成することができ、開発の初期段階で手間を減らすことができます。
APIのテストとインタラクション
Swagger UIを使用すると、APIのエンドポイントをブラウザ上でインタラクティブに操作し、リクエストを送信してレスポンスを確認できます。これにより、APIのテストが簡単になり、実際の利用シーンに近い形で動作を確認できるため、開発中に不具合を早期に発見しやすくなります。
チーム間での協力
APIはしばしば複数のチームで開発されます。例えば、バックエンドチーム、フロントエンドチーム、モバイルチーム、外部開発者などが協力して開発を進めますが、Swaggerを使うことで、仕様を一貫して共有することができます。これにより、チーム間でAPIの理解が深まり、協力的に開発を進めることができます。
バージョン管理と変更管理
APIは変更が加わることが多く、特に新しい機能の追加や既存の機能の改善が必要になることがあります。Swaggerでは、APIのバージョンを管理し、変更を追跡できるため、バージョンごとに異なるAPI仕様を保持し、過去のバージョンとの互換性を保つことができます。
Swagger の主要なツールたち
Swagger について冒頭で、「APIを管理するためのツールセット」と書きました。
ツールセットと言うからには複数のツールの集まりである訳ですが、ここからは具体的にどんなツール・機能があるのかできるだけ簡潔に見ていきましょう。
Swagger UI
まずSwagger UIですが、これはブラウザ上でAPIをインタラクティブに操作できるエディタです。
APIエンドポイントを試しながら動作を確認できるため、開発者のみならず、APIのユーザーにも役立ちます。
Swagger Editor
次にSwagger Editor。これはAPIの仕様書を書くためのエディタで、きれいなYAMLまたはJSON形式でAPIの構造を記述することができます。
オンラインエディタであるため、編集をした後にリアルタイムでプレビューできたりと、API設計の効率化をサポートしてくれます。
Swagger Codegen
そして、Swagger Codegenは、さまざまなプログラミング言語向けのクライアントやサーバーサイドコードを自動生成するツールです。
これにより、手動でコードを書く手間が省け、APIの実装を迅速かつ一貫性を持って行うことができます。
Swagger の主要なツールといえばこの3つですが他にも、バージョン管理やレビュー機能を利用して複数人で効率的にAPI開発を進められるためのプラットフォームを提供してくれる Swagger Hub や、APIエンドポイントを直接呼び出してテストを実行し、その結果を基にSwagger形式の仕様書を自動的に作成することでAPI開発の初期段階で役立つような Swagger Inspector などがあります。
興味のある方は是非ほかのツールについても調べてみてください。
Swaggerを使ったAPIドキュメント作成の基本ステップ
Swaggerを使ってAPIドキュメントを作成するときの簡単な流れは以下の通りです。
1. Swagger Editorのセットアップ
最初にすることは、Swagger Editorを環境にインストール、もしくはオンラインエディタを使用して準備することです。
VS Code などのエディタを使っている方向けにも Swagger Editor を利用するために、OpenAPI (Swagger) Editorといった拡張機能が存在します。
2 .API仕様の記述
次に行うのはAPI仕様の記述です。記述する際にはYAML形式かJSON形式で記述を行います。
【YAML形式で記述されたAPI仕様の例】
openapi: 3.0.0
info:
title: Sample API
description: This is my sample API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
APIの各エンドポイントやパラメータを詳細に定義し、可能であればサンプルデータも記載しておきましょう。これにより、APIの使用状況が明確になります。
3. ドキュメントの確認・視覚化
作成したAPI仕様書を使って、Swagger UIでドキュメントを視覚的に確認します。これにより、APIの使い方が誰でも簡単に理解できるようになります。また、Swagger UIでは、APIを実際に呼び出してテストすることもできます。
【上記YAMLファイルから実際に出来上がるドキュメントの例】
4. ドキュメントの公開
APIの仕様を記述し終えたら、次はそのドキュメントを公開する方法です。Swagger UIや各種ツールを用いれば、公開は非常に簡単です。
チーム内での共有がオンラインでスムーズに行える点が Swagger を用いるメリットです。
私が Swagger を実際に使ってみた感想
まず、Swagger Editorを使ったAPI仕様の記述ですが、YAML形式やJSON形式で記載することでシンプルな階層構造になっていてドキュメント化する前の記述の段階でも頭の中で整理しやすいです。
また、Swagger UIを使ったドキュメントの例を上記で上げましたが、あのドキュメントは自動生成されるので、YAMLやJSONでファイルを作るだけで、自動的に見やすい、かつレスポンシブなデザインでドキュメントをつくってくれるという点は非常に便利だと感じました。
まとめ
ここまで述べたように、 Swagger はAPIドキュメントを簡単に作成し管理できる便利なツールです。その将来性も高く、多くの企業が導入を進めているので、効率的なAPI開発を行うために Swagger の知識やスキルを身に着けるのも良いかもしれません。
また、本記事では Swagger について取り上げましたが、APIを管理するためのツールは他に、 Postman や Google Cloud の Apigee 、AWS の AWS API Gateway などがありますので、気になった方は、これらのサービスについてもぜひ調べてみてはいかがでしょうか。
*1:現在、OpenAPIはAPI仕様の標準規格となっており、Swaggerはその仕様を利用するツールセット、という関係。ツールという視点で見ると Swagger という呼び方が一般に浸透していたりツール名にはSwagger という言葉が残っているため本記事では単に Swagger と呼ぶ。
*2:システム全体を独立した小さなサービスで構築し、効率的に管理できるようにする設計（アーキテクチャ）のこと。
*3:APIが提供する特定の機能を実行するためのURL（またはURI）のこと。
