Koa2 を使用して Swagger を Node.js プロジェクトに統合する方法について説明した記事

この記事では、Koa2 を使用して Swagger を Node.js プロジェクトに統合し、API ドキュメントを自動的に生成する方法を説明します。 Swagger の基本概念、関連する NPM パッケージを紹介し、詳細なコード例と説明を使用してプロセス全体を示します。

Swagger とは

Swagger は、RESTful API 用のドキュメント生成ツールです。開発者が API を迅速かつ正確に作成、保守、レビューするのに役立ちます。 Swagger には次の利点があります。

• API ドキュメントを自動的に生成し、手動で作成する作業負荷を軽減します
• デバッグと検証を容易にするビジュアルな API インターフェイス テスト ツールを提供します
• サポート優れた汎用性とスケーラビリティを備えた複数の言語とフレームワーク

Koa2 プロジェクトの作成

まず、Koa2 に基づいて Node.js プロジェクトを作成する必要があります。次のコマンドを使用してプロジェクトを作成できます: [推奨される関連チュートリアル: nodejs ビデオ チュートリアル 、プログラミング指導 ]

mkdir koa2-swagger-demo
cd koa2-swagger-demo
npm init -y

次に、Koa2 と関連する依存関係をインストールします。

npm install koa koa-router --save

Swagger 関連の依存関係をインストールする

次に、Swagger 関連の NPM パッケージをインストールする必要があります。このチュートリアルでは、koa2-swagger-ui と swagger-jsdoc を使用します。 Swagger UI の表示と API ドキュメントの生成にそれぞれ使用されます。

npm install koa2-swagger-ui swagger-jsdoc --save

Swagger の構成

プロジェクトのルート ディレクトリに、Swagger を構成するための swagger.js という名前のファイルを作成します。構成コードは次のとおりです。

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: '我是标题',
            version: '1.0.0',
            description: '我是描述',
        },
        //servers的每一项，可以理解为一个服务,实际项目中，可自由修改
        servers: [
            {
                url: '/api',
                description: 'API server',
            },
        ],
    },
    apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

// 如果有Swagger规范文件转TS的需求，可在此处保留Swagger规范文件到本地，方便使用
//fs.writeFileSync('swagger.json', JSON.stringify(swaggerSpec, null, 2));

module.exports = swaggerSpec;

ここでは、options という名前のオブジェクトを定義します。これには、Swagger の基本情報と API インターフェイスのソース (つまり、ルーティング ファイル) が含まれています。 ）。次に、swagger-jsdoc を使用して API ドキュメントを生成し、エクスポートします。

API インターフェイスの作成

次に、routes という名前のフォルダーを作成し、その中に users.js という名前のファイルを作成します。ユーザー関連の API インターフェイス。 users.js ファイルに次のコードを記述します:

const Router = require('koa-router');
const router = new Router();

/**
* @swagger
* tags:
*   name: Users
*   description: User management
*/

/**
* @swagger
* components:
*   schemas:
*     User:
*       type: object
*       properties:
*         id:
*           type: integer
*           description: The user ID.
*         name:
*           type: string
*           description: The user's name.
*         email:
*           type: string
*           description: The user's email.
*       required:
*         - id
*         - name
*         - email
*/

/**
* @swagger
* /users:
*   get:
*     summary: Retrieve a list of users
*     tags: [Users]
*     responses:
*       200:
*         description: A list of users.
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 $ref: '#/components/schemas/User'
*/
router.get('/users', async (ctx) => {
    const users = [
        { id: 1, name: 'John Doe', email: 'john.doe@example.com' },
        { id: 2, name: 'Jane Doe', email: 'jane.doe@example.com' },
    ];
    ctx.body = users;
});

module.exports = router;

コメントの簡単な分析:

1. tags: この部分は名前を定義します。 「ユーザー」のラベル。タグは、API インターフェイスを分類およびグループ化するために使用されます。ここでは、ラベルの名前は「Users」、説明は「users.js のインターフェース」です。

   /**
    * @swagger
    * tags:
    *   name: Users
    *   description: users.js下的接口
    */

2. components および schemas: この部分では、「User」という名前のデータ モデルを定義します。データ モデルは、API インターフェイスで使用されるデータ構造を記述します。この例では、「User」モデルには 3 つのプロパティが含まれています: id (整数型、ユーザー ID を表す)、name (文字列型、ユーザー名を表す)、および email (ユーザーの電子メールを表す文字列タイプ)。同時に、id、name、および email 属性が必須としてマークされます。

   /**
    * @swagger
    * components:
    *   schemas:
    *     User:
    *       type: object
    *       properties:
    *         id:
    *           type: integer
    *           description: id.
    *         name:
    *           type: string
    *           description: name.
    *         email:
    *           type: string
    *           description: email.
    *       required:
    *         - id
    *         - name
    *         - email
    */

3. /users API インターフェイス: この部分では、ユーザー リストを取得するための API インターフェイスを定義します。これは、パス /users を使用した GET リクエストを記述しています。このインターフェースは、前に定義した「Users」タグを使用します。さらに、ステータス コード 200 を含む成功応答も定義されており、ユーザー リストが返されることを示します。応答のコンテンツ タイプは application/json で、その構造は「User」モデルを含む配列です。

   $ref: '#/components/schemas/User' は、components で以前に定義された schemas を参照する参照構文です。 User という名前のデータ モデル。

   /**
   * @swagger
   * /users:
   *   get:
   *     summary: 获取用户列表
   *     tags: [Users]
   *     responses:
   *       200:
   *         description: success.
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 $ref: '#/components/schemas/User'
   */

このコードは、ユーザー管理インターフェイス、データ モデル、応答形式の詳細を API ドキュメントに提供します。 Swagger JSDoc はこれらの注釈を解析し、対応する OpenAPI ドキュメントを生成します。

API ドキュメントの生成

次に、プロジェクトで Swagger UI を有効にする必要があります。プロジェクトのルート ディレクトリで、app.js という名前のファイルを作成し、次のコードを記述します。

const Koa = require('koa');
const Router = require('koa-router');
const swaggerUI = require('koa2-swagger-ui').koaSwagger;
const swaggerSpec = require('./swagger');
const usersRoutes = require('./routes/users');

const app = new Koa();
const router = new Router();

router.use('/api', usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    '/swagger',
    swaggerUI({
        routePrefix: false,
        swaggerOptions: {
            spec: swaggerSpec,
        },
    })
);

app.use(router.routes()).use(router.allowedMethods());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is running at http://localhost:${PORT}`);
});

ここでは、koa2-swagger-ui および swagger-jsdoc によって生成された API ドキュメントをインポートしました。次に、Swagger UI を表示するために /swagger という名前のルートを定義しました。最後に、ユーザー関連の API インターフェイスを /api パスにマウントします。

Test

node app.js

ブラウザで開くhttp://localhost:3000/swagger Swagger UI と自動生成された API ドキュメントが表示されます。

概要

この記事では、Swagger を統合し、Koa2 に基づいた Node.js プロジェクトで API ドキュメントを自動的に生成する方法を詳しく紹介しました。 koa2-swagger-ui と swagger-jsdoc を使用すると、API インターフェイスのオンライン ドキュメントを簡単に生成し、ビジュアル テストに Swagger UI を利用できます。

Swagger を統合する主な手順は次のとおりです。

• 関連する依存関係のインストール: koa2-swagger-ui および swagger-jsdoc
• Swagger の構成: swagger の作成.js ファイル、API ドキュメントの基本情報とインターフェイス ソースを定義します。
• API インターフェイスを作成します。Swagger アノテーション構文を使用してインターフェイス情報を記述します。
• Swagger UI を有効にする: Swagger のルーティングを構成します。 app.js に UI を追加し、API を追加します。 ドキュメントが渡されます。
• プロジェクトを実行し、Swagger UI にアクセスします。

上記の手順により、自動生成を実現できます。プロジェクト内の API ドキュメントの更新とレビューにより、開発効率と共同作業効果が向上します。同時に、Swagger UI が提供するテスト ツールを使用して、API インターフェイスの正確性と安定性を簡単に検証することもできます。

swagger-to-ts を使用して、Swagger 仕様ファイルを TypeScript タイプのファイルに変換できます。

ノード関連の知識の詳細については、nodejs チュートリアル を参照してください。

以上がKoa2 を使用して Swagger を Node.js プロジェクトに統合する方法について説明した記事の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。