マブスバックエンド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を吐き出してくれます。