はじめまして、TalentX, EMの岸本です。 TalentXでは開発業務の他、バックエンドチームのマネジメントを担当しています。
昨今のAPI開発において、OpenAPIを用いた仕様の定義は一般化していると思いますが、 その運用方法に関して、TalentXで工夫している点などを踏まえてご紹介させていただきます。
スプレッドシートからの脱却
私が入社した数年前のタイミングでは、APIの仕様はスプレッドシートで管理されていました。 その際の課題として
- バージョン管理が難しく、適切なロールバックや変更タイミングの把握ができない。
- Slack等でのコミュニケーションになってしまう、変更場所の把握が難しいなど、レビューに時間がかかる。
- 記載者によってフォーマット・記述方法が異なってしまう。
といった点がありました。
OpenAPIでAPI仕様を記述することによって、
- JSONやYAMLで書かれたファイルをGitで管理できるため、バージョン管理が容易。
- Git管理が可能なことにより、GitHub, GitLabといったサービスでのレビューが可能。
- 記述方法が仕様として定まっているため、記述者によるばらつきが起きにくい。
といった恩恵があるため導入を検討しました。
OpenAPIの課題
しかしOpenAPIの導入に関して、いくつか課題もありました。
- JSONやYAMLで記載する必要があるため、OpenAPIに慣れていないメンバーの学習コストが高い。
- JSON、YAMLといったファイルを仕様書としてみるためにUI (Swagger UI 等)ツールを用意しないといけない。
- スプレッドシートからOpenAPIに移行しても実際の仕様とコードのずれが生じてしまう。
といった点です。
まず、上の2点の課題に関して、Stoplight というツールを導入するといったアプローチを検討しました。
Stoplightの導入
Stoplight とはOpenAPIでの仕様管理を支援するプラットフォームであり、いくつかの強力な機能があります。
基本的な点としてはドキュメンテーションUIとエディターが用意されており、仕様定義の見やすさと容易さが担保できます。
GUIで仕様の記述が可能
JSONやYAMLを意識することなくOpenAPIの仕様に則った記述ができるため、OpenAPIに慣れていないメンバーでも簡単に記述することができました。 フォームの内容を埋めていく・選択していくだけで仕様が作成でき、仕様に準拠していない部分はWarningやErrorを知らせてくれるため、OpenAPIに詳しくなくとも作成できます。
またGUIでの作成のため、作成画面自体も仕様が把握しやすいのですが、UIプレビューへの切り替えも容易で記述中の確認もスムーズに行えます。 GUIとテキスト形式の入力方式を切り替えられるため、JSON, YAML形式で記述したい時にも対応できます。
GitHubとの連携が可能
TalentXのGit管理ツールはGitHubを採用しています。 StoplightはGitHubと連携が可能で、GitHubのレポジトリを同期し、レポジトリで管理されているファイルを編集・コミットすることができます。
TalentXでは
- GitHubからブランチをpush
- Stoplight上でブランチを取得し、ファイルを編集しコミット
- GitHub上でPRを出す
という運用を基本的にとっています。 誤字修正などJSON, YAMLを直接変更したい場合などは、Stoplightを経由せずPRを出すことなどもあります。
ブラウザのWebアプリケーションとして動作する
Webアプリケーションであるため、記載した内容のリンクをPRに貼り、綺麗なUIでレビューするといったことが可能になりました。 JSON, YAMLを直接レビューするより、情報把握がしやすくレビュアー・レビュイーの負担が軽減されています。
また他にもモックサーバーを提供していたりAPI開発に便利な機能が提供されています。
コード生成
Stoplightの導入によってOpenAPIでの仕様作成に関する課題は解消できました。
その一方で、スプレッドシート時代から残る、 仕様とコードの乖離 という点は解決できていません。
ただOpenAPIという標準化された規格に移行することで、そのエコシステムを利用することが可能になりました。
OpenAPI generator
OpenAPI Generator はOpenAPIファイルからサーバー・クライアント用のファイルを生成できるツールです。
API仕様を実装する際のコードのほか、APIをcallする時のコード生成としても利用できます。 また 対応言語 も広く、主要な言語はカバーしている他、一部の言語はフレームワーク用のものも用意されています。
TalentXでは、
- API開発をする際、リクエスト・レスポンスの型定義の生成
- 他システムのAPIをcallする際のクライアントコード生成
といった使い方をしています。
利用方法
利用方法はいくつかあり、TalentXではDockerを利用する形を採用しています。
$ docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ --input-spec /local/path/to/openapi.yaml \ --generator-name go \ --output /local/path/to/output
--input-spec,-i= 読み込むOpenAPIのファイルパスを記載--generator-name,-g= 生成するコードのジェネレーター名(言語/サーバーorクライアント/FW)を記載docker run --rm openapitools/openapi-generator-cli listで取得することが可能です。phpphp-laravelrubyruby-on-railsgogo-gin-serverなどを指定します。
--output,-o= 生成されたコードを出力するパスを記載
以上が基本的な使い方になり、 GitHub や Doc に詳しく説明されています。
工夫している点
詳細な利用方法は上記のサイトで説明されているため省きますが、TalentXでの運用で１つ工夫している点はテンプレートをカスタマイズしている点です。
出力されるファイルはOpenAPI generatorで管理されているテンプレートに基づいて出力されるのですが、そのテンプレートは
この場所におかれています。
このテンプレートを利用せずに独自のテンプレートを利用したい場合は -t , --template-dir オプションを利用しテンプレートファイルを置くディレクトリを指定します。
$ docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ --input-spec /local/path/to/openapi.yaml \ --generator-name go \ --output /local/path/to/output \ --template-dir /local/path/to/template-directory
こちらのディレクトリに、利用するジェネレーターが使用しているテンプレートファイルと同名のファイルを配置しておくとそちらが優先されるようになります。
例をあげると、 go-server ジェネレーターを利用する場合以下のテンプレートが使用されており、指定したディレクトリに model.mustache を配置するとモデル定義部分が優先されます。
- Dockerfile.mustache - README.mustache - api.mustache - controller-api.mustache - error.mustache - go.mod.mustache - helpers.mustache - impl.mustache - logger.mustache - main.mustache - model.mustache - openapi.mustache - partial_header.mustache - routers.mustache - service.mustache
TalentXの利用例として、Go言語のサーバーサイドの実装におけるリクエストの型を生成する際に、APIの仕様を利用したStructのタグを追加・変更しています。
このように適宜カスタマイズを行いながらAPI仕様とコードの乖離がないような開発を実現しています。
最後に
長文にも関わらずここまで読んでいただきありがとうございました。 API開発における仕様定義部分にフォーカスして執筆しましたが、その部分に課題を持つ方のヒントになれば幸いです。
TalentXでは一緒に働く仲間を募集しております。カジュアル面談も行っていますので気になる方はぜひご応募いただければ幸いです！ i-myrefer.jp
