Swaggerとは？APIのドキュメント生成方法（SwaggerのHello World）をご紹介

＜目次＞

(１) Swaggerとは？APIのドキュメント生成方法（SwaggerのHello World）をご紹介
　やりたいこと
　概要
　(１-１) STEP1：Node.js （含むnpm）のインストール
　(１-２) STEP2：Expressおよびswagger-ui-expressをインストールします。
　(１-３) STEP3：app.jsファイルを作成する
　(１-４) STEP4：swagger.jsonファイルを作成
　(１-５) STEP5：疎通

(１) Swaggerとは？APIのドキュメント生成方法（SwaggerのHello World）をご紹介

やりたいこと

＞目次にもどる

背景／概要

背景

Swaggerのサービスが生まれた背景として、以下の点が挙げられる。
・①APIの標準化不足：開発者によって、開発スタイルが異なり、APIの互換性や一貫性が不足していた
　→(例) エンドポイント、エラーレスポンスの形式）
・②ドキュメント化が難しい：APIの動作を記述する効果的なツールが無く、開発者がAPIの仕様を理解し辛い
　→(例) パラメータや戻り値の型が不明、発生するエラーの記述が無いドキュメントなど）
・③クロスプラットフォーム対応：異なる開発言語やプラットフォーム間で、互換性の確保が困難
　→(例) 特有の認証方法や、.NET等のフレームワーク対応など
・④クライアントSDKの生成：APIからクライアントSDK
　→(例) Swaggerの文脈ではAPI仕様からAPIを操作するためのライブラリ等を自前で作成する必要がある

概要

(１-１) STEP1：Node.js （含むnpm）のインストール

（図１１１）

↓

・②インストール

（図１１２①）

↓

～中略～

↓

・③インストール完了

（図１１２②）

・④完了確認

> node -v

（図１１３）

(１-２) STEP2：Expressおよびswagger-ui-expressをインストールします。

> cd [作業ディレクトリ]
> npm install express swagger-ui-express

（図１３１）

↓

（図１３２）

（出力結果例）

added 59 packages in 4s

7 packages are looking for funding
  run `npm fund` for details

(１-３) STEP3：app.jsファイルを作成する

// expressモジュールを読み込む
const express = require('express');

// swagger-ui-expressモジュールを読み込む
const swaggerUi = require('swagger-ui-express');

// swagger.jsonファイルを読み込む
// このファイルはAPIの仕様を定義し、Swagger UIで表示されます。
const swaggerDocument = require('./swagger.json');

// Expressアプリケーションを作成する
const app = express();

// '/api-docs'エンドポイントでswagger-uiを利用するためのミドルウェアを設定する
// swagger-ui-expressモジュールのserve関数とsetup関数を使用して、swaggerDocument（swagger.jsonファイル）を提供します。
// つまり、'/api-docs'エンドポイントにアクセスすると、Swagger UIが表示され、swaggerDocumentに記載されたAPI仕様が表示されます。
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// '/hello'エンドポイントでGETリクエストを処理するハンドラを設定する
app.get('/hello', (req, res) => {
  res.send('Hello World!');
});

// アプリケーションをポート3000でリッスンし、サーバーを起動します。
app.listen(3000, () => {
  console.log('Example app listening on port 3000!');
});

（図３１１）

(１-４) STEP4：swagger.jsonファイルを作成

{
  "swagger": "2.0",
  "info": {
    "title": "Hello World API",
    "description": "A simple example of a RESTful API using Swagger",
    "version": "1.0.0"
  },
  "basePath": "/",
  "paths": {
    "/hello": {
      "get": {
        "summary": "Say Hello",
        "description": "Returns a simple greeting message",
        "produces": ["text/plain"],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

（図４１１）

(１-５) STEP5：疎通

> node app.js