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

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.

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

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

Copier après la connexion

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

npm install koa koa-router --save

Copier après la connexion

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

Copier après la connexion

配置Swagger

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

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

const swaggerSpec = swaggerJSDoc(options);

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

module.exports = swaggerSpec;

Copier après la connexion

这里，我们定义了一个名为options的对象，包含了Swagger的基本信息和API接口的来源（即我们的路由文件）。然后，我们使用swagger-jsdoc生成API文档，并将其导出。

编写API接口

现在，我们来创建一个名为routes的文件夹，并在其中创建一个名为users.js的文件，用于定义用户相关的API接口。在users.js文件中，我们将编写以下代码：

const Router = require(&#39;koa-router&#39;);
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&#39;s name.
*         email:
*           type: string
*           description: The user&#39;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: &#39;#/components/schemas/User&#39;
*/
router.get(&#39;/users&#39;, async (ctx) => {
    const users = [
        { id: 1, name: &#39;John Doe&#39;, email: &#39;john.doe@example.com&#39; },
        { id: 2, name: &#39;Jane Doe&#39;, email: &#39;jane.doe@example.com&#39; },
    ];
    ctx.body = users;
});

module.exports = router;

Copier après la connexion

注释简析：

tags：这部分定义了一个名为"Users"的标签。标签用于对API接口进行分类和分组。在这里，标签名为"Users"，描述为"users.js下的接口"。
```
/**
 * @swagger
 * tags:
 *   name: Users
 *   description: users.js下的接口
 */
```
Copier après la connexion
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
 */
```
Copier après la connexion
/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: &#39;#/components/schemas/User&#39;
*/
```
Copier après la connexion
Configuration de Swagger

swagger.js

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

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

router.use(&#39;/api&#39;, usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    &#39;/swagger&#39;,
    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}`);
});

Copier après la connexion

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

Copier après la connexion

Analyse des commentaires :

tags

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

GET

/users

200

application/json

$ref : '#/components/schemas/User'

schémas

components

Utilisateur

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.