OpenAPIによるRESTful APIの仕様管理
OpenAPIというRESTful APIのフォーマットを利用した仕様管理について記載する。
業務においてRESTful APIの開発を行っている。
REST APIの改修に合わせて、仕様変更が必要になり、仕様のドキュメントの管理が煩雑になる。
そのため、RESTful APIのフォーマットであるOpenAPIを利用して仕様を管理する。
OpenAPIとは
APIの仕様に関するオープンな規格。IBM, Microsoftなどが参加している。
OpenAPIはテキストベースのフォーマット(JSON/YAML)であり、プログラムから扱いやすい。
OpenAPIを扱うための様々なツールからなるエコシステムが存在する。
OpenAPIは、Swagger2.0というAPIのフォーマットを拡張したものである。
OpenAPIによるユーザー向けドキュメントの生成
OpenAPI自体はJSON/YAMLファイルであり、RESTful APIを呼び出す利用者が閲覧するには適していない。
OpenAPIのファイルをユーザー向けドキュメントを生成するツールについて紹介する。
個人的には ReDocのドキュメントがユーザーにとって分かりやすいと思う。
ReDoc
OpenAPIを元にユーザー向けのドキュメント(HTML)を生成する。
サーバーサイドレンダリング(SSR)の他、静的ファイルの生成も可能である。
インストール
npmでインストールを行う。
npm install -g redoc-cli
サーバーサイドレンダリング
OpenAPIファイル openapi_example.yamlから
redoc-cli serve openapi_example.yaml
静的ファイル生成
OpenAPIファイル openapi_example.yamlからHTMLファイルを生成する。
redoc-cli bundle openapi_example.yaml
Swagger UI
OpenAPIを元に実行可能なユーザー向けのサイトを生成する。
ドキュメントの閲覧の他、APIの実行が可能である。
Swagger
Swagger にはOpenAPIを支援するために他にも次のツールが存在する。
- Swagger Editor ブラウザベースのOpenAPIエディタ。
- Swagger Codegen OpenAPIをサーバーサイド・クライアントサイドから利用するソースコードを生成するツール。
OpenAPIのプログラムからの利用
OpenAPI Generator での利用
OpenAPIを元に様々な言語でのRESTful APIのクライアントサイド・サーバーサイドプログラムのひな型を生成するプログラム。
Postmanでの利用
PostmanにはOpenAPIのフォーマット(JSON/YAML)を読み込む機能がある。
それを元にPostmanの設定をインポート可能である。
OpenAPIの生成
スクラッチからAPIを作成する場合にはOpenAPIから作成し始められばよい。
しかし、業務において、
- 既にプログラムが存在しており、それを元に
- 設定情報を元にOpenAPIの仕様を変更する必要がある。
という問題があった。
そのため、既存のソースコードからOpenAPIを生成するのに役立つツールについて記載する。
業務においてC#を使うことが多いため、MicrosoftのC#関連のツールの紹介である。
OpenAPI.NET
C#でOpenAPIの仕様を記述して、OpenAPIを生成するためのライブラリ。
C#の機能の支援を受けてOpenAPIを記載することで、コード補完の利用・型によるミスの発見が可能である。
また、設定情報を元にOpenAPIを変更して出力することが行いやすい。
OpenAPI.NET.CSharpAnnotations
C#にアノテーションを追加して、それを元にOpenAPIを生成するツールも存在する。
OpenAPI.NET.CSharpAnnotations公式
OpenAPIのエディタ
OpenAPIをスクラッチから記載するために役立つエディタについて記載する。
私はVisual Stuido Codeを利用しているが、大規模なAPIの設計を行う場合にはSpotlight Studioを使うのがよいかもしれない。
OpenAPI (Swagger) Editor (Visual Studio Extension)
Visual Studio Code で OpenAPIを記述するための拡張機能。
- ひな型の作成
- ナビゲーション
- インテリセンス
- プレビュー
などの機能が存在する。
OpenAPI (Swagger) Editor Visual Studio Marketplace
Spotlight Studio
OpenAPIエディタ。
OpenAPIのLintやドキュメントの生成などの機能がある。
Discussion