In einem Artikel wird erläutert, wie man mit Koa2 Swagger in Node.js-Projekte integriert

In diesem Artikel erfahren Sie, wie Sie mit Koa2 Swagger in ein Node.js-Projekt integrieren, um automatisch API-Dokumentation zu generieren. Wir stellen die Grundkonzepte von Swagger und verwandten NPM-Paketen vor und demonstrieren den gesamten Prozess anhand detaillierter Codebeispiele und Erklärungen.

Was ist Swagger?

Swagger ist ein RESTful-API-Dokumentgenerierungstool, das Entwicklern dabei helfen kann, API-Dokumente schnell und genau zu schreiben, zu verwalten und zu überprüfen. Swagger bietet die folgenden Vorteile:

• Automatisches Generieren von API-Dokumenten, wodurch der Arbeitsaufwand für das manuelle Schreiben reduziert wird.
• Bietet visuelle Tools zum Testen der API-Schnittstelle, um das Debuggen und Überprüfen zu erleichtern.
• Unterstützt mehrere Sprachen und Frameworks sowie eine gute Vielseitigkeit und Skalierbarkeit.

Erstellen eines Koa2-Projekts

Zuerst müssen wir ein Node.js-Projekt basierend auf Koa2 erstellen. Sie können den folgenden Befehl verwenden, um ein Projekt zu erstellen: [Verwandte Tutorial-Empfehlungen: nodejs-Video-Tutorial, Programmierlehre]

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

Dann installieren Sie Koa2 und zugehörige Abhängigkeiten:

npm install koa koa-router --save

Installieren Sie Swagger-bezogene Abhängigkeiten

Als nächstes werden wir Sie müssen das Swagger-bezogene NPM-Paket installieren. In diesem Tutorial verwenden wir koa2-swagger-ui und swagger-jsdoc. Wird zum Anzeigen der Swagger-Benutzeroberfläche bzw. zum Generieren der API-Dokumentation verwendet. 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'
   */

   Swagger konfigurieren

Erstellen Sie im Stammverzeichnis des Projekts eine Datei mit dem Namen swagger.js zum Konfigurieren von Swagger. Der Konfigurationscode lautet wie folgt:

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

Hier definieren wir ein Objekt mit dem Namen options, das die grundlegenden Informationen von Swagger und die Quelle der API-Schnittstelle (d. h. unsere Routing-Datei) enthält. Dann verwenden wir swagger-jsdoc

API-Dokumentation generieren und exportieren.

API-Schnittstelle schreiben

Jetzt erstellen wir einen Ordner mit dem Namen routes und darin einen Ordner mit dem Namen users Datei, die zum Definieren benutzerbezogener API-Schnittstellen verwendet wird. In die Datei „users.js“ schreiben wir den folgenden Code:

node app.js

Kommentaranalyse:

tags: This Abschnitt definiert eine Bezeichnung namens „Benutzer“. Tags werden zur Klassifizierung und Gruppierung von API-Schnittstellen verwendet. Hier heißt die Bezeichnung „Benutzer“ und die Beschreibung lautet „Schnittstelle unter users.js“.

rrreee

Komponenten und Schemata: Dieser Teil definiert ein Datenmodell mit dem Namen „Benutzer“. Das Datenmodell beschreibt die in der API-Schnittstelle verwendeten Datenstrukturen. In diesem Beispiel enthält das „Benutzer“-Modell drei Attribute: id (Ganzzahltyp, der die Benutzer-ID darstellt), name (String-Typ, der den Benutzernamen darstellt) und email (String-Typ, der die E-Mail-Adresse des Benutzers darstellt). Gleichzeitig werden die Attribute id, name und email als erforderlich markiert. rrreee

🎜🎜/users API-Schnittstelle: Dieser Teil definiert eine API-Schnittstelle zum Abrufen der Benutzerliste. Es beschreibt eine GET-Anfrage mit dem Pfad /users. Diese Schnittstelle verwendet das zuvor definierte Tag „Benutzer“. Darüber hinaus definiert es auch eine erfolgreiche Antwort mit dem Statuscode 200, der angibt, dass eine Benutzerliste zurückgegeben wird. Der Inhaltstyp der Antwort ist application/json und ihre Struktur ist ein Array, das das „Benutzer“-Modell enthält. 🎜🎜$ref: '#/components/schemas/User' ist eine Referenzsyntax, die sich auf die zuvor unter components A definierten schemas bezieht Datenmodell mit dem Namen Benutzer. 🎜rrreee🎜🎜🎜Dieser Code stellt der API-Dokumentation Details zur Benutzerverwaltungsschnittstelle, zum Datenmodell und zum Antwortformat bereit. Swagger JSDoc analysiert diese Anmerkungen und generiert entsprechende OpenAPI-Dokumente. 🎜🎜API-Dokumentation generieren🎜🎜Als nächstes müssen wir die Swagger-Benutzeroberfläche im Projekt aktivieren. Erstellen Sie im Stammverzeichnis des Projekts eine Datei namens app.js und schreiben Sie den folgenden Code: 🎜rrreee🎜Hier haben wir die von koa2-swagger-ui und swagger-jsdoc generierte API-Dokumentation importiert. Dann haben wir eine Route namens /swagger definiert, um die Swagger-Benutzeroberfläche anzuzeigen. Abschließend mounten wir die benutzerbezogene API-Schnittstelle im /api-Pfad. 🎜🎜Test🎜rrreee🎜Öffnen Sie 🎜http://localhost:3000/swagger🎜 im Browser. Sie sehen die Swagger-Benutzeroberfläche und die automatisch generierte API-Dokumentation. 🎜

Zusammenfassung

In diesem Artikel haben wir ausführlich vorgestellt, wie man Swagger integriert und automatisch API-Dokumentation in einem Koa2-basierten Node.js-Projekt generiert. Durch die Verwendung von koa2-swagger-ui und swagger-jsdoc können wir ganz einfach Online-Dokumentation für API-Schnittstellen erstellen und die Swagger-Benutzeroberfläche für visuelle Tests nutzen.

Die Hauptschritte zur Integration von Swagger sind wie folgt:

• Zugehörige Abhängigkeiten installieren: koa2-swagger-ui und swagger-jsdoc
• Swagger konfigurieren: Erstellen Sie die Datei swagger.js, definieren Sie die grundlegenden Informationen und die Schnittstellenquelle der API Dokument
• Schreiben Sie die API-Schnittstelle: Verwenden Sie die Swagger-Annotationssyntax, um Schnittstelleninformationen zu beschreiben
• Aktivieren Sie die Swagger-Benutzeroberfläche: Konfigurieren Sie die Route der Swagger-Benutzeroberfläche in app.js und übergeben Sie das API-Dokument daran.
• Führen Sie das Projekt aus und greifen Sie auf die Swagger-Benutzeroberfläche zu

Durch die oben genannten Schritte können wir die automatische Generierung, Aktualisierung und Überprüfung von API-Dokumenten im Projekt implementieren und so die Entwicklungseffizienz und die Auswirkungen auf die Zusammenarbeit verbessern. Gleichzeitig können wir mithilfe der von Swagger UI bereitgestellten Testtools auch problemlos die Richtigkeit und Stabilität der API-Schnittstelle überprüfen.

Swagger-Spezifikationsdateien können mit swagger-to-ts in Dateien vom Typ TypeScript konvertiert werden.

Weitere Informationen zu Knoten finden Sie unter: nodejs-Tutorial!

Das obige ist der detaillierte Inhalt vonIn einem Artikel wird erläutert, wie man mit Koa2 Swagger in Node.js-Projekte integriert. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!