🙌
SwaggerでAPIのドキュメント化を簡単に

2024/12/07に公開
API
 はじめにAPIを開発する際、仕様書の共有や管理が必要になります。手動でドキュメントを作成すると時間がかかり、APIの更新時に整合性を保つのも大変、、そんな課題を解決してくれるのがSwaggerです。
Swaggerは、APIの設計、ドキュメントの作成と管理を簡単にするためのツールです。この記事では、Swaggerの基本から具体的な活用方法までを解説します。

 ちなみに、、弊社では、フリーランスエンジニアの方を募集しており、

サーバーサイド、フロントエンド、ネイティブアプリ等、それぞれの領域で活躍できるプロジェクトがあります！

サーバーサイドでも、API構築やDB構築、認証・認可の実装、セキュリティ対策など、それぞれのプロジェクトで対応領域は様々です！
興味がある方は、ぜひ下記フォームに回答いただけますと幸いです。

👉 フォームはこちら

 Swaggerとは？Swaggerは、以下のような機能を提供するAPIドキュメンテーションツールのセットです↓

ドキュメントの自動生成：コードからAPIの仕様書を自動的に作成

インタラクティブなUI：Swagger UIから、ブラウザ上でAPIの動作を簡単に確認可能

API設計の標準化：OpenAPI Specificationに準拠しており、チーム全体で統一された仕様を共有可能

 Swaggerのメリット効率的なドキュメント管理

→ 自動生成されるので、手動で更新する手間が省けます
簡単なテスト

→ Swagger UIを使えば、実際のAPIリクエストをインタラクティブに試すことができます
チームでの共有が容易

→ ブラウザでアクセス可能なドキュメントは、開発者だけでなくクライアントや他の関係者にもわかりやすい形で提供できます

 Swaggerを始める準備以下では、Node.js（Express）を使ったプロジェクトにSwaggerを導入する手順を解説します。

 必要なツールとパッケージSwaggerを使うには、以下のパッケージをインストールします：
npm install swagger-ui-express swagger-jsdoc

swagger-ui-express：ExpressでSwagger UIを提供するためのパッケージ

swagger-jsdoc：コードコメントからOpenAPI仕様書を生成するツール

 Swaggerのセットアップ方法
 1. Swagger設定ファイルの作成Swaggerの設定を定義するファイルを作成します。以下、基本的な設定例です。
const swaggerJsDoc = require('swagger-jsdoc');

const swaggerOptions = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "My API Documentation",
      version: "1.0.0",
      description: "APIのドキュメント",
    },
    servers: [
      {
        url: "http://localhost:3000",
      },
    ],
  },
  apis: ["./routes/*.js"], // API仕様が記述されたファイルを指定
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
module.exports = swaggerDocs;

 2. ExpressにSwagger UIを組み込む次に、Swagger UIをExpressに組み込みます。
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocs = require('./swagger'); // 作成した設定ファイルをインポート

const app = express();

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

app.listen(3000, () => {
  console.log("サーバーが起動しました。APIドキュメントは http://localhost:3000/api-docs で確認できます。");
});
これで、http://localhost:3000/api-docsにアクセスすると、Swagger UIが表示されます

 3. コメントでAPI仕様を定義するSwaggerでは、コード内に記述したコメントを元にAPI仕様書を生成します。以下は、ユーザー情報を取得するAPIの例です：
/**
 * @swagger
 * /users:
 *   get:
 *     summary: ユーザー情報の取得
 *     responses:
 *       200:
 *         description: ユーザーのリスト
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                     example: 1
 *                   name:
 *                     type: string
 *                     example: 太郎
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: "太郎" }, { id: 2, name: "花子" }]);
});
このコメントに基づいて、Swagger UIに自動的に仕様書が生成されます。

 Swaggerを活用するベストプラクティス初期段階で導入する

プロジェクトの開始時にSwaggerを導入することで、APIの仕様とドキュメントの整合性を保ちやすくなります。
API仕様のレビューを行う
Swagger UIを活用して、開発チームやクライアントと仕様を確認しながら進めましょう。
バージョン管理を徹底する
APIの変更に伴い、Swagger仕様書もバージョン管理を行い、過去の仕様を追跡できるようにします。
必要な情報を過不足なく記載
各エンドポイントの目的、リクエストパラメータ、レスポンス形式を明確に記述することで、利用者の理解を助けます。

 まとめSwaggerは、API開発の効率化に不可欠なツールです。ドキュメントを自動生成し、インタラクティブなUIを提供することで、チームの生産性向上や仕様管理の負担軽減に貢献します。
この記事を参考に、プロジェクトでSwaggerを活用して、よりスマートなAPI開発を実現してください！
お問い合わせやご意見がありましたら、お気軽にご連絡ください！

 おわりに繰り返しになりますが、弊社では、フリーランスエンジニアの方を募集しております！
熱意を持って新しいプロジェクトに挑戦したい方、様々な大規模開発プロジェクトに興味のある方は、下記フォームにてあなたの経歴をご回答ください！
👉 フォームはこちら
たくさんのご応募、お待ちしております！
はじめに

ちなみに、、

Swaggerとは？

Swaggerのメリット

Swaggerを始める準備

必要なツールとパッケージ

Swaggerのセットアップ方法

1. Swagger設定ファイルの作成

2. ExpressにSwagger UIを組み込む

3. コメントでAPI仕様を定義する

Swaggerを活用するベストプラクティス

まとめ

おわりに

Discussion
