「OpenAPIを利用すると何ができるようになる？」
「OpenAPIとSwaggerは何が違う？」
OpenAPIとはWebアプリケーション同士の安全な通信のために、どのような項目・形式で仕様を記載すべきか定義したフォーマットのことです。Excelなどで管理していたAPI仕様書をOpenAPIを用いて作成することで、フォーマットが統一されて管理しやすくなります。
本記事では、以下の内容を詳しく解説します。
- OpenAPIの概要
- OpenAPIでできること
- OpenAPIのメリット・デメリット
- OpenAPIの書き方
- OpenAPIを利用する際に役立つツール
本記事を読むことで、OpenAPIを導入することでできるようになることや、Swaggerとの違いが分かります。 開発やテストを効率化したいと考えている企業の方は、ぜひご一読ください。
OpenAPIの導入を検討している組織の方、必見！
OpenAPIを利用すると何ができるようになる？
記述形式が統一されたドキュメントを自動生成したり、モックサーバー構築からテストまでを簡単に実行できるようになります。なお、OpenAPIを使用して実装するWebAPIには、Webアプリケーション同様に脆弱性が存在するため対策が必要です。方法はこちらの資料をご覧ください。
OpenAPIとは
OpenAPIとは「Open API Spesification」の略で、REST APIの記述フォーマットを指します。REST APIとは、Webアプリケーション同士の情報のやり取りを安全に行うための規格のことです。つまりOpenAPIは、安全な通信のために「どのような項目をどのような形式で記載すればよいのか」という仕様を定義しています。
OpenAPIはさまざまなプログラミング言語で利用でき、コンピュータと人間の両方が判読できるのが特徴です。導入すれば、API仕様に沿ったドキュメントの自動作成・モックサーバーの作成・テストの実行などができるようになります。
API仕様書の作成はExcelなどでも可能ですが、修正やバージョン管理がしにくいという問題がありました。しかしOpenAPIなら、API仕様書の様式が統一されるため管理が非常に楽になります。
OpenAPIとSwaggerとの違い
OpenAPIはもともと「Swagger」という名前で、SwaggerがOpenAPI Initiativeへ寄贈されたことで名称がOpenAPIに変更になりました。現在のSwaggerは、REST APIの設計に利用するツールセットを指す言葉として使われています。
Swaggerのツールセットには「Swagger Editor」「Swagger UI」「Swagger Codegen」などがあります。
| ツールセット | 概要 |
|---|---|
| Swagger Editor | API仕様書を編集するためのツール。プレビュー機能があり、編集しながら完成形のドキュメントを確認できる。 |
| Swagger UI | OpenAPIの記述をドキュメントとして生成・表示するためのツール。Swagger EditorでプレビューできるのはSwagger UIの機能によるもの。 |
| Swagger Codegen | OpenAPIの記述をもとに、サーバーでデータ処理を行うためのコードを自動生成するツール。C#・Java・Pythonなど、数多くの言語に対応している。 |
OpenAPIとオープンAPIの違い
「OpenAPI」と「オープンAPI」は、発音は同じでも意味が異なる点に注意が必要です。カタカナ表記のオープンAPIは、ソフトウェアが提供している機能を他のWebアプリケーションから利用できるようにする仕組みのことを指します。REST APIの記述フォーマットを指すOpenAPIとは別物です。
例えばオープンAPIで銀行口座とデータ連携すると、アプリから簡単に口座残高を確認できたり、入出金明細を取得して家計簿を付けたりできます。銀行システムとデータ連携すれば、利用したいサービスで改めて口座情報を入力する必要がありません。手間が省け、サービスがより利用しやすくなります。
OpenAPIでできる3つのこと
OpenAPIを利用すると、以下の3つのことができるようになります。
- OpenAPIドキュメントの自動生成
- モックサーバーの構築
- テストの実行
OpenAPIでできることを知り、導入を検討しましょう。
1. OpenAPIドキュメントの自動生成
OpenAPIを利用すると、記載内容や記述形式が統一されたドキュメントを自動生成できます。API仕様書の作成者によって内容に相違が出ることがなくなるため、開発者同士で仕様のやり取りをスムーズに行えます。
2. モックサーバーの構築
OpenAPIではテストで使用するモックサーバーの構築が可能です。モックサーバーとは、Webサーバーがすぐに用意できないときに、ブラウザ側でテスト的に使用するための簡易サーバーです。モックには「見せかけの」「試作品」などの意味があります。
モックサーバーはプログラムの動作をすぐ確認したいときに便利で、開発やテストをスムーズに実施できます。
3. テストの実行
OpenAPIで生成したドキュメントをもとに、テストを実行することが可能です。テストケースが大量に自動生成されるため、開発者が気付かなかったバグを発見することができます。機能・負荷・セキュリティなど、Webアプリケーションが相互通信するために満たすべき基準を確認するのに役立ちます。
OpenAPIのメリット・デメリット
近年注目を集めているマイクロサービスアーキテクチャによりWeb APIを利用した大規模システム開発が活発に行われています。OpenAPIには便利な機能があるため、このWeb APIを利用したシステム開発が非常に簡単になります。
OpenAPIのメリット
OpenAPIを利用する具体的なメリットは、以下の通りです。
API仕様書のフォーマットを統一できる
API仕様書の作成者が変わっても、記述項目などのフォーマットを統一できます。
API仕様書の記述が楽になる
ドキュメントの自動生成ができるツールを導入すれば、API仕様書の記述が非常に楽になります。
バージョン管理が楽になる
更新履歴が把握できるため、Excel等で作成したAPI仕様書に比べてバージョン管理が楽になります。
コーディング・テストを効率化できる
ツールを使用することでコードやテストケースが自動生成されるため、人の手で作成するよりも効率的になります。
OpenAPIのデメリット
OpenAPIによる仕様の統一はフォーマットに従ってただ生成するだけですが、コード生成など便利な仕組みを利用するためにはツールの導入が必要です。しかしツールの導入には、以下の2つのデメリットがあります。
OpenAPIを使いこなすためにある程度学習が必要
OpenAPIの機能を活用するには、さまざまなツールの導入が必要となります。ツールの使い方を覚えるために、ある程度の学習が求められるでしょう。
最新のOpenAPIに非対応のツールがある
ツールがバージョンアップされず、最新のOpenAPIに対応していないことがあります。
OpenAPIの書き方
OpenAPIの記述方法には「YAML形式」と「JSON形式」の2種類があります。どちらの形式で記述してもアウトプットは同じで、Swagger Editorを利用すればYAMLとJSON同士で相互変換が可能です。
それぞれの特徴は下記の通りですが、どちらもJavaScript・C／C++・Java・Python・PHPなど、幅広いプログラミング言語で活用されています。
| 記述方法 | 特徴 |
|---|---|
| YAML形式 | 判読性が高く、文法が覚えやすい記述方法。プログラミング言語間のデータ交換が簡単にできる。ログファイルのメッセージ交換や、設計ファイルのデータ化に使用される。 |
| JSON形式 | データ構造が単純で、人間の目でも判読しやすい記述方法。軽量なデータ交換ができる他、読み込みや加工もしやすい。 |
OpenAPIを利用する際に役立つ5つのツール
OpenAPIを利用してWebシステム開発を行う際には、以下のようなツールの活用がおすすめです。やりたいことが実現できるツールを導入して、開発やテストを効率化させましょう。
- Stoplight Studio
- Redoc
- Prism
- Postman
- OpenAPI Generator
1. Stoplight Studio
Stoplight StudioはOpenAPIのフォーマットに沿った仕様書を、GUIで直感的に作成できるツールです。GUIとは、画面上に表示されているボタンやプルダウンメニューなどを用いて、マウスでクリックするだけで操作できるインターフェースです。
コードを記述せずにAPI仕様書を作成できるため、手で記述するよりも楽になり、作成時間も節約できます。Swagger Editorでも仕様書を作成できますが、学習コストを抑えるならStoplight Studioがおすすめです。
| Stoplight Studio | |
|---|---|
| 特徴 |
|
| どのような企業 or 方におすすめか |
|
2. Redoc
Redocは、HTMLベースのドキュメントを生成・閲覧できるようにするツールです。デザインが見やすく、カスタマイズしやすい特徴があります。なおRedocの他には、Swagger UIやspectacleでもドキュメントの閲覧が可能です。
| Rodec | |
|---|---|
| 特徴 |
|
| どのような企業 or 方におすすめか |
|
3. Prism
Prismは、API仕様書をもとにモックサーバーを構築するためのツールです。YAML形式のファイルを読み込ませるだけで、すぐにモックサーバーを起動できます。
| Prism | |
|---|---|
| 特徴 |
|
| どのような企業 or 方におすすめか |
|
4. Postman
Postmanは、APIのテストを実行するためのツールです。トークンを設定してHTTPリクエストを送信すると、エンドポイントが正常に動作しているか確認できます。UIが洗練されており、初心者でも迷うことなく簡単に操作できるのが特徴です
| Postman | |
|---|---|
| 特徴 |
|
| どのような企業 or 方におすすめか |
|
5. OpenAPI Generator
OpenAPI Generatorは、OpenAPI仕様書からAPIサーバー／クライアントのコードを自動生成するツールです。生成されるコードはテンプレートを用いてカスタマイズすることもできます。
| OpenAPI Generator | |
|---|---|
| 特徴 |
|
| どのような企業 or 方におすすめか |
|
WebAPIの脆弱性対策
OpenAPIによって、さまざまな言語で作成・利用しているRest APIを簡単にテスト・管理できるようになります。仕様に沿ったテストを行うことで正しく実装できているか確認できますが、セキュリティを強固にしたいのであればWebAPIの脆弱性診断がお勧めです。
WebAPIの脆弱性診断には以下の課題があるため、対策が後回しになってしまっている企業も少なくありません。
- 認可や認証の仕組みなど、WebAPI固有の脆弱性はWebアプリケーション診断ではカバーできない
- WebAPIを診断するには「パラメータ値を大量に入力する」「モック画面を作成する」などの手作業が多く、時間がかかる
WebAPIの診断方法には「手動診断」と「ツール診断」がありますが、診断に必要なデータの準備やシナリオ作成を自動で実施してくれる診断ツールを利用するとコストや時間の削減ができるのでおすすめです。また、近年はWebアプリケーション診断にAPI診断機能が追加されているツールもあるので、導入すると効率的に診断が実施できるでしょう。
ネットワークやWebアプリケーションと同様に、WebAPIにも脆弱性は存在します。WebAPIの利活用が飛躍的に増えている今、サイバー攻撃を未然に防ぐためにも脆弱性診断を実施しましょう。
▼脆弱性診断ツールのWebAPI診断機能について
脆弱性診断ツール（サービス）｜有料・無料の違いと5つの選定ポイント 内「Web API診断のチェック項目」
▼脆弱性診断ツールについて
脆弱性診断（セキュリティ診断）とは｜必要性からやり方まで、すべて解説
まとめ｜OpenAPIを活用して開発の効率化を
OpenAPIとはWebアプリケーション同士の安全な通信のために、どのような項目・形式で仕様を記載すべきか定義したフォーマットのことです。OpenAPIを導入すると、以下のことができるようになります。
- OpenAPIドキュメントの生成
- モックサーバーの構築
- テストの実行
なお、上記の機能を使うには、以下のようなツールを導入する必要があります。
- Stoplight Studio
- Redoc
- Prism
- Postman
- OpenAPI Generator
OpenAPIならびに必要なツールを導入して、開発やテストを効率化しましょう。
