ExpressとSwagger UIの連携

はじめに

前回、Expressを使ってバックエンドのAPIを作ってみたので、今回はSwagger UIを使ってAPIドキュメントを作成してみる。

Swagger UIとは

詳細はネットで調べればわかると思うので概要だけ

APIのリソース可視化（ドキュメント化）
- エンドポイント、リクエストとレスポンスのパラメータ、モデル定義が一目でわかる
- これにより、APIの概要や仕様を簡単に理解できる
APIエンドポイントのテストツール
- 設定したエンドポイントに対してリクエストパラメータを付けて自由にリクエストが投げれる
- これにより、実際にAPIエンドポイントを呼び出して動作をテストすることができる

これ以外にもあるかもしれないけど、今回の利用方法としてはこれだけ。

本記事のゴール

Express環境でSwagger UIの表示とSwagger UIでAPIリクエストを投げてみる。

環境

Windows 10 64bit
Node.js：19.1.0
Express：4.18.2
swagger-ui-express：5.0.0

事前準備

前回と同じ環境ができていること

Swagger UIの設定手順

swagger-ui-expressのインストール

npm install swagger-ui-express

app.jsへの追記

追記した部分のみ記載する

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

swagger.jsonの作成

Swagger UIの定義となる、swagger.jsonファイルを作成する。

0から書くのは厳しいので、定義ファイルを作成できるツールであるSwagger Editorからサンプルを拾ってきて修正した。

現状エンドポイントはルート（/）のgetしか用意していないのでそれだけ記載している。

{
  "openapi": "3.0.3",
  "info": {
    "title": "Express API with Swagger",
    "description": "API documentation for Express app with Swagger",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Get a greeting",
        "responses": {
          "200": {
            "description": "Successful response",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}