BLOG

ブログ

マブスバックエンドMTG#2 – APIドキュメントを活用した話

こんにちは、タロウです。

先月から始めたバックエンド部門もミーティングですが、
6月も開催しましたので様子を紹介します!

今回は・・

たまたまですが、みんな在宅ワークの日だったのでオンラインでした。

そしてスピーカーは僕(タロウ)です。

テーマ

「フロントエンドをスムーズに進めるにあたりAPIドキュメントをコード化した話」
Speaker: タロウ

開発を行う際に全員が全員、フロントエンド・バックエンドの両方をできる人ばかりではないと思います。

フロントエンドの開発と同時進行でバックエンドを進めることがあり、
APIのインターフェースを共有するのにスプレッドシートや別ツールだと
人によって書きっぷりが違う、粒度が違う・・と(途中でメンテがおざなりになる)課題が出てきました。

統一した書き方ができる、必要な情報のルールを設定できるドキュメントジェネレータAPI Docを導入し課題を解消することができました。

/**
 * @api {get} /sample-api サンプルAPI
 * @apiVersion 1.0.0
 * @apiGroup common
 * @apiPermission admin
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
router.get(
  '/sample-api',
  wrap(async (req: Request, res: Response, next: NextFunction) => {
    // ~~~~~~~~~
  })
);

このような感じでjavadocのように記載すると、APIドキュメントのHTMLを吐き出してくれます。

APIDocで出力したドキュメント

このように見やすく出力してくれます。

また、メンバーによってはバックエンドを起動しないでフロントエンド開発をすることもあるので、
開発メンバーが誰でも見られるようにAmplifyConsoleでデプロイを行い共有する工夫も行なっています。

テーマを通じて

極力保守性良く、メンテナンスの手間が少なくしたく導入したAPI Docですが、
現在も開発が続いているプロジェクトでは、スムーズなフロントエンド開発ができており、かなり有効活用できています!

今まで途中でメンテナンスされないドキュメントを多く見てきたので、
そのようなことを発生させないように工夫していきたいです。

余談

今回はオンライン開催だったのでお菓子はなく・・

その代わり(?)に好きな耳かきが話題に上がりました。

金属製のもの、スマホで見れるものなどある中、
永坂さんはベーシックな耳かきがお好きなようです。

ちなみに僕は、三段になっている金属製推しです。

最後に

短い時間で行なっているミーティングですが、
今後も、各自プロジェクトで生かすことのできる内容や再認識できる内容が出てきそうです。

また7月開催予定なので様子をお伝えしていきます!