Un article explique comment utiliser Koa2 pour intégrer Swagger dans les projets Node.js

Dans cet article, nous explorerons comment utiliser Koa2 pour intégrer Swagger dans un projet Node.js afin de générer automatiquement la documentation de l'API. Nous présenterons les concepts de base de Swagger, les packages NPM associés, et démontrerons l'ensemble du processus avec des exemples de code et des explications détaillés.

Qu'est-ce que Swagger

Swagger est un outil de génération de documents API RESTful qui peut aider les développeurs à rédiger, maintenir et réviser des documents API rapidement et avec précision. Swagger présente les avantages suivants :

• Génère automatiquement des documents API, réduisant ainsi la charge de travail d'écriture manuelle
• Fournit des outils de test d'interface API visuelle pour faciliter le débogage et la vérification
• Prend en charge plusieurs langages et frameworks et offre une bonne polyvalence et évolutivité

Création d'un projet Koa2

Tout d'abord, nous devons créer un projet Node.js basé sur Koa2. Vous pouvez utiliser la commande suivante pour créer un projet : [Recommandations de didacticiel associées : Tutoriel vidéo Nodejs, Enseignement de la programmation]

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

Ensuite, installez Koa2 et les dépendances associées :

npm install koa koa-router --save

Installez les dépendances liées à Swagger

Ensuite, nous vous devez installer le package NPM lié à Swagger. Dans ce tutoriel, nous utiliserons koa2-swagger-ui et swagger-jsdoc. Utilisé pour afficher l'interface utilisateur Swagger et générer la documentation de l'API respectivement. koa2-swagger-ui和swagger-jsdoc。分别用于展示Swagger UI和生成API文档。

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

配置Swagger

在项目根目录下，创建一个名为swagger.js的文件，用于配置Swagger。配置代码如下：

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： 这部分定义了一个名为"Users"的标签。标签用于对API接口进行分类和分组。在这里，标签名为"Users"，描述为"users.js下的接口"。

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

2. components和schemas： 这部分定义了一个名为"User"的数据模型。数据模型描述了API接口中使用的数据结构。在这个例子中，"User"模型包含三个属性：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接口。它描述了一个GET请求，路径为/users。这个接口使用了之前定义的"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'
   */

   Configuration de Swagger

Dans le répertoire racine du projet, créez un fichier nommé swagger.js pour configurer Swagger. Le code de configuration est le suivant :

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}`);
});

Ici, nous définissons un objet nommé options, qui contient les informations de base de Swagger et la source de l'interface API (c'est-à-dire notre fichier de routage). Ensuite, nous utilisons noreferrer">swagger-jsdoc

Générer la documentation de l'API et l'exporter.

Ecriture de l'interface API

Maintenant, créons un dossier nommé routes et créons-y un dossier nommé users. fichier, utilisé pour définir les interfaces API liées à l'utilisateur. Dans le fichier users.js, nous écrirons le code suivant :

node app.js

Analyse des commentaires :

tags : Ceci La section définit une étiquette appelée « Utilisateurs ». Les balises sont utilisées pour classer et regrouper les interfaces API. Ici, l'étiquette est nommée « Utilisateurs » et la description est « Interface sous users.js ».

rrreee

composants et schémas : Cette partie définit un modèle de données nommé "Utilisateur". Le modèle de données décrit les structures de données utilisées dans l'interface API. Dans cet exemple, le modèle "Utilisateur" contient trois attributs : id (type entier, représentant l'ID utilisateur), name (type de chaîne, représentant le nom d'utilisateur) et email (Type String, représentant l'email de l'utilisateur). Dans le même temps, les attributs id, name et email sont marqués comme obligatoires. rrreee

🎜🎜/users Interface API : Cette partie définit une interface API pour obtenir une liste d'utilisateurs. Il décrit une requête GET avec le chemin /users. Cette interface utilise la balise "Utilisateurs" définie précédemment. De plus, il définit également une réponse réussie avec un code d'état de 200, indiquant qu'une liste d'utilisateurs est renvoyée. Le type de contenu de la réponse est application/json et sa structure est un tableau contenant le modèle « Utilisateur ». 🎜🎜$ref : '#/components/schemas/User' est une syntaxe de référence, qui fait référence aux schémas précédemment définis sous components A modèle de données nommé Utilisateur. 🎜rrreee🎜🎜🎜Ce code fournit à la documentation de l'API des détails sur l'interface de gestion des utilisateurs, le modèle de données et le format de réponse. Swagger JSDoc analyse ces annotations et génère les documents OpenAPI correspondants. 🎜🎜Générer la documentation de l'API🎜🎜Ensuite, nous devons activer l'interface utilisateur Swagger dans le projet. Dans le répertoire racine du projet, créez un fichier appelé app.js et écrivez le code suivant : 🎜rrreee🎜Ici, nous avons importé la documentation API générée par koa2-swagger-ui et swagger-jsdoc. Ensuite, nous avons défini une route nommée /swagger pour afficher l'interface utilisateur de Swagger. Enfin, nous montons l’interface API relative à l’utilisateur sur le chemin /api. 🎜🎜Test🎜rrreee🎜Ouvrez 🎜http://localhost:3000/swagger🎜 dans le navigateur. Vous verrez l'interface utilisateur Swagger et la documentation de l'API générée automatiquement. 🎜

Résumé

Dans cet article, nous avons présenté en détail comment intégrer Swagger et générer automatiquement la documentation de l'API dans un projet Node.js basé sur Koa2. En utilisant koa2-swagger-ui et swagger-jsdoc, nous pouvons facilement générer une documentation en ligne pour les interfaces API et utiliser l'interface utilisateur Swagger pour les tests visuels.

Les principales étapes pour intégrer Swagger sont les suivantes :

• Installer les dépendances associées : koa2-swagger-ui et swagger-jsdoc
• Configurer Swagger : Créer le fichier swagger.js, définir les informations de base et la source de l'interface de l'API document
• Écrivez l'interface API : utilisez la syntaxe d'annotation Swagger pour décrire les informations de l'interface
• Activez l'interface utilisateur Swagger : configurez l'itinéraire de l'interface utilisateur Swagger dans app.js et transmettez-lui le document API
• Exécutez le projet et accédez à l'interface utilisateur Swagger

Grâce aux étapes ci-dessus, nous pouvons implémenter la génération, la mise à jour et la révision automatiques des documents API dans le projet, améliorant ainsi l'efficacité du développement et les effets de collaboration. Dans le même temps, en utilisant les outils de test fournis par Swagger UI, nous pouvons également facilement vérifier l'exactitude et la stabilité de l'interface API.

Les fichiers de spécifications Swagger peuvent être convertis en fichiers de type TypeScript à l'aide de swagger-to-ts.

Pour plus de connaissances sur les nœuds, veuillez visiter : tutoriel Nodejs !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!