TypeScriptのExpressでOpenAPI（Swagger）を導入する方法！初心者向けバックエンド開発API仕様書自動生成完全ガイド

1. バックエンド開発とREST APIの基本を知ろう

1. バックエンド開発とREST APIの基本を知ろう

Webアプリケーションやスマホアプリの裏側では、バックエンドと呼ばれる仕組みが動いています。バックエンドは、ユーザーからは直接見えないサーバーの中で、データの保存や計算などの処理を行う重要な役割を持っています。このバックエンドのプログラムを作る言語として、作動が安定していて間違いに気づきやすいTypeScript（タイプスクリプト）というプログラミング言語が今とても人気を集めています。

そして、このバックエンドと、ユーザーが実際に触る画面（フロントエンド）との間でデータをやり取りするための窓口になる仕組みをREST API（レスト エーピーアイ）と呼びます。APIは、特定のURLにデータを送ると、決まった形式で結果を返してくれる連絡通路のようなものです。この連絡通路がどのようなルールで動いているのかを明確に記した書類が、開発において非常に重要になります。

2. OpenAPIとSwaggerの役割とメリット

2. OpenAPIとSwaggerの役割とメリット

APIを作る際、どのURLにどんなデータを送ればいいのかというルールが書かれた説明書のことをAPI仕様書（エーピーアイしようしょ）といいます。この仕様書を世界共通のルールで記述するための世界標準の規格がOpenAPI（オープン エーピーアイ）です。昔はエクセルなどで説明書を作っていましたが、手作業で更新するとプログラムの内容とズレが生じてしまう問題がありました。

そこで登場するのがSwagger（スワガー）というツールです。Swaggerを使うと、OpenAPIの形式で書かれた設定ファイルを読み込んで、Webブラウザ上で綺麗で見やすい説明書の画面を自動的に作ってくれます。さらに、その画面上にあるボタンを押すだけで、実際にデータを送信してバックエンドの動きをテストできるという、強力で便利な機能を持っています。

3. 開発を始めるためのExpress環境を準備しよう

3. 開発を始めるためのExpress環境を準備しよう

まずは、TypeScriptでバックエンドのサーバーを作るための土台となるExpress（エクスプレス）というフレームワークを準備します。フレームワークとは、サーバー作りに必要な基本機能があらかじめセットになった道具箱のようなものです。今回は、Node.jsというパソコン上で動く環境を使い、コマンドを入力して必要な部品を集めていきます。

最初に、プログラムを動かすための最もシンプルなExpressサーバーのコードを用意します。以下のプログラムは、サーバーを起動して、画面に接続があったときに文字を返すだけの簡単な仕組みです。プロジェクトの初期設定を行い、必要な拡張部品をインストールした状態からスタートします。

import express from 'express';

const app = express();
const port = 3000;

app.use(express.json());

app.get('/api/welcome', (req, res) => {
    res.json({ message: 'バックエンドの準備が完了しました！' });
});

app.listen(port, () => {
    console.log(`サーバーが起動しました。ポート番号：${port}`);
});

上記のコードは、パソコンの3000番という通り道を使って通信を待ち受ける設定です。URLの後ろに「/api/welcome」とつけてアクセスすると、歓迎のメッセージがデータとして返ってくる仕組みになっています。これがAPIの最も基本的な形になります。

4. Swagger導入に必要な部品をインストールする

4. Swagger導入に必要な部品をインストールする

Expressのサーバーが準備できたら、次にOpenAPIの画面を表示するために必要な専用の部品を追加します。パソコンの画面にある黒い画面（ターミナルやコマンドプロンプト）を開き、パッケージを管理するツールを使って、インストールという作業を行います。今回使用する部品は主に2つあります。

1つ目は「swagger-ui-express」という部品で、これがWebブラウザにあの綺麗な説明書画面を映し出す役割を持っています。2つ目は「swagger-jsdoc」という部品で、これはプログラムのコメント欄に書いたメモ書きを自動で集めて、OpenAPIの規格に沿ったデータに変換してくれる便利な翻訳機です。これらをTypeScriptで安全に使うための型定義データも一緒に取り込みます。インストールの命令を実行すると、パソコンの中に自動でファイルがダウンロードされます。

5. OpenAPIの基本設定コードを作成しよう

5. OpenAPIの基本設定コードを作成しよう

部品が揃ったら、今度は仕様書全体のタイトルやバージョン情報などの基本情報を定義するコードを書いていきます。プログラムに対して、「これから作るAPIの名前はこれで、このURLで待ち受けます」という案内図を教えてあげる作業です。この設定を記述することで、Swaggerの画面の最上部に綺麗なタイトルが表示されるようになります。

以下のプログラムは、先ほどのExpressサーバーのコードに、Swaggerの設定を付け加えたものです。これによって、どのファイルを読み込んで説明書を作るかのルートが決まります。設定用のオブジェクトを作成し、それを部品に渡すことで準備を行います。

import express from 'express';
import swaggerJSDoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const app = express();
const port = 3000;

const swaggerOptions = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: '初心者向けタスク管理API仕様書',
            version: '1.0.0',
            description: 'TypeScriptとExpressで作る初めてのAPIドキュメントです。',
        },
        servers: [
            {
                url: 'http://localhost:3000',
            },
        ],
    },
    apis: ['./src/app.ts'],
};

const swaggerSpec = swaggerJSDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(port, () => {
    console.log('仕様書画面は http://localhost:3000/api-docs で確認できます');
});

このプログラムを実行すると、新しく「/api-docs」という専用のURLが作られます。ここにパソコンのWebブラウザからアクセスすることで、自動生成された説明書の画面が表示されるようになります。まだ中身のAPI情報を書いていないため、タイトルだけが存在する状態です。

6. コメントを使ってAPIの詳細な仕様を記述する

6. コメントを使ってAPIの詳細な仕様を記述する

全体の枠組みができたら、次はいよいよ個々のAPIの詳しいルールを追加していきます。swagger-jsdocの素晴らしいところは、特別なファイルを作らなくても、いつものプログラムのすぐ上に「コメント文」として仕様を書き込める点です。特定の書き方に従ってコメントを記述すると、それをツールが自動で読み取ってくれます。

今回は、例として「ユーザーの情報を取得するAPI」を作ってみましょう。どのようなデータが手に入るのか、成功したときにはどんな形式の数字や文字が返ってくるのかを、細かくコメントの中に指定していきます。プログラムの中に直接仕様を埋め込むため、コードの変更があったときにも修正が簡単になります。

import express from 'express';
const app = express();

/**
 * @openapi
 * /api/user:
 * get:
 * summary: 会員情報を取得します
 * description: 登録されているユーザーの名前と年齢を返却するAPIです。
 * responses:
 * 200:
 * description: データの取得に成功した場合
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * name:
 * type: string
 * example: 鈴木太郎
 * age:
 * type: number
 * example: 20
 */
app.get('/api/user', (req, res) => {
    res.json({ name: '鈴木太郎', age: 20 });
});

コメントの中にある「@openapi」という文字が合図になっており、そこから下が仕様書の内容として認識されます。データの型が文字列（string）なのか数値（number）なのかといった、TypeScriptの型システムと非常によく似た概念を使って中身を定義していくのが特徴です。

7. データを送信するPOST処理の仕様書を作ろう

7. データを送信するPOST処理の仕様書を作ろう

APIには、データを取得するだけでなく、新しく情報を登録するための仕組みもあります。これをPOST（ポスト）処理と呼びます。例えば、新しくブログの記事を投稿したり、ユーザー登録を行ったりするときに使われます。この場合は、送信する側がどのようなデータを準備して送るべきかというルールを仕様書に書く必要があります。

次の例では、「新しいタスクを登録する」という想定のAPIと、その仕様書の書き方を解説します。送られてくるデータの項目名や、それが必須のものなのかどうかを設定として盛り込んでいきます。これによって、利用者はどんなデータを送ればいい迷わずに済みます。

import express from 'express';
const app = express();
app.use(express.json());

/**
 * @openapi
 * /api/todo:
 * post:
 * summary: 新しいタスクを追加する
 * description: やるべきことのタイトルを受け取り、保存するためのAPIです。
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * required:
 * - title
 * properties:
 * title:
 * type: string
 * example: 部屋の掃除をする
 * responses:
 * 201:
 * description: 無事に登録が完了した状態
 */
app.post('/api/todo', (req, res) => {
    const { title } = req.body;
    console.log(`新しいタスク: ${title}`);
    res.status(201).json({ status: '成功しました' });
});

「requestBody」という項目を使うことで、送信されてくるデータの形を定義しています。必須項目には「required」という指定をしておくことで、画面上でテストする際にも分かりやすく強調表示されるようになり、開発のミスを未然に防ぐことができます。

8. ブラウザで仕様書画面を開いてテストを実行する

8. ブラウザで仕様書画面を開いてテストを実行する

すべての設定とコードが書き終わったら、プログラムを実行してWebブラウザから確認を行います。指定したURLにアクセスすると、これまでコメントに書いてきた内容が綺麗なグラフィックの画面となって出現します。緑色や青色のブロックでAPIが整理されており、一目で全体の構造が理解できるようになります。

画面に表示されたAPIのブロックをクリックして開くと、詳細な説明が表示されます。そこにある「Try it out（試してみる）」というボタンをクリックして、さらに「Execute（実行）」というボタンを押すことで、その場で実際にバックエンドのサーバーへ通信が飛びます。返ってきた結果が画面の下部に表示されるため、プログラムが正しく動いているかをその場で即座に確認できます。

このように、仕様書の作成と動作テストが同時に行える環境が整うことで、バックエンド開発の効率は劇的に向上します。チームで開発をするときも、この画面のURLを仲間に共有するだけで、どのような仕様なのかを正確に伝えることができるようになります。