まえがき
-
最近はBFFアーキテクチャの採用により、サーバサイドは内部(Internal)APIとしてAPIを作成することが多い
-
チームで開発するために、どのAPIが何を示しているかはわかりやすくしておきたい
- サーバ・フロントどちらを触るときでもAPI定義を見れば実装できるようにしたい
- 各エンドポイントが何をしているか、コードを見ればわかるけど毎回したくはない
-
チーム開発でAPI開発をするときにどのようなツールを利用していたかについて記載する。
前提
- いわゆるREST APIを採用 (gRPCではない）
- OpenAPI3.0 を仕様
VSCode拡張機能
- Swagger Viewer
- API定義をプレビューできる拡張機能
- 拡張機能名はSwaggerとついているが、OpenAPI3.0でも問題なくプレビューが可能
- いわゆるライブリロード機能があり、編集→反映がスムーズに行えるのが良い
- 図はサンプルなAPIを表示した例
OpenAPI extension for Visual Studio Code
- OpenAPI extension for Visual Studio Code
- 新規作成時にテンプレートから生成が可能
- 一方previewのような形では使えないのでそこまでは利用していない。
Redoc
-
Redoc
- デモはこちら : https://redocly.github.io/redoc/
- OpenAPIの定義からPreviewを生成するOSS
- example にあるように、API定義と、cdnの読み込みさえ書けば良い
<body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
</body>
- oapiの場合 sepc.yamlを指定すれば良い。
- 実運用上は GitHub Pagesのようなところにホスティングして開発者が確認できるようにしている
- 図はサンプルAPIを表示した例
oapi-codegen
- oapi-codegen
- Goでサーバサイドを書くために、oapi-codegenを利用してサーバサイドのコードを生成している
まとめ
- 各種ツールを利用することで、内部API開発を効率的にできるようになった。
- API定義があることで、サーバー <-->フロント間でやり取りする際の共通言語として利用できるようになった。
- また、サーバーサイドを主としていた人がフロント側を行う際にもよい取っ掛かりとなった。