Inhaltsverzeichnis
Was ist Swagger?
Erstellen eines Koa2-Projekts
Installieren Sie Swagger-bezogene Abhängigkeiten
配置Swagger
编写API接口
注释简析:
API-Schnittstelle schreiben" >

API-Schnittstelle schreiben

Kommentaranalyse:
rrreee
Zusammenfassung
Heim Web-Frontend js-Tutorial In einem Artikel wird erläutert, wie man mit Koa2 Swagger in Node.js-Projekte integriert

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

Apr 01, 2023 am 07:30 AM
前端 node.js 测试

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.

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

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
Nach dem Login kopieren

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

npm install koa koa-router --save
Nach dem Login kopieren

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-uiswagger-jsdoc。分别用于展示Swagger UI和生成API文档。

npm install koa2-swagger-ui swagger-jsdoc --save
Nach dem Login kopieren

配置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;
Nach dem Login kopieren

这里,我们定义了一个名为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;
Nach dem Login kopieren

注释简析:

  1. tags: 这部分定义了一个名为"Users"的标签。标签用于对API接口进行分类和分组。在这里,标签名为"Users",描述为"users.js下的接口"。

    /**
     * @swagger
     * tags:
     *   name: Users
     *   description: users.js下的接口
     */
    Nach dem Login kopieren
  2. componentsschemas: 这部分定义了一个名为"User"的数据模型。数据模型描述了API接口中使用的数据结构。在这个例子中,"User"模型包含三个属性:id(整数类型,表示用户ID)、name(字符串类型,表示用户名)和email(字符串类型,表示用户电子邮件)。同时,idnameemail属性都被标记为必需。

    /**
     * @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
     */
    Nach dem Login kopieren
  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'
    */
    Nach dem Login kopieren

    Swagger konfigurieren

  4. 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}`);
});
Nach dem Login kopieren

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
Nach dem Login kopieren

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!

Erklärung dieser Website
Der Inhalt dieses Artikels wird freiwillig von Internetnutzern beigesteuert und das Urheberrecht liegt beim ursprünglichen Autor. Diese Website übernimmt keine entsprechende rechtliche Verantwortung. Wenn Sie Inhalte finden, bei denen der Verdacht eines Plagiats oder einer Rechtsverletzung besteht, wenden Sie sich bitte an admin@php.cn

Heiße KI -Werkzeuge

Undresser.AI Undress

Undresser.AI Undress

KI-gestützte App zum Erstellen realistischer Aktfotos

AI Clothes Remover

AI Clothes Remover

Online-KI-Tool zum Entfernen von Kleidung aus Fotos.

Undress AI Tool

Undress AI Tool

Ausziehbilder kostenlos

Clothoff.io

Clothoff.io

KI-Kleiderentferner

AI Hentai Generator

AI Hentai Generator

Erstellen Sie kostenlos Ai Hentai.

Heißer Artikel

R.E.P.O. Energiekristalle erklärten und was sie tun (gelber Kristall)
2 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌
Repo: Wie man Teamkollegen wiederbelebt
4 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island Abenteuer: Wie man riesige Samen bekommt
4 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌

Heiße Werkzeuge

Notepad++7.3.1

Notepad++7.3.1

Einfach zu bedienender und kostenloser Code-Editor

SublimeText3 chinesische Version

SublimeText3 chinesische Version

Chinesische Version, sehr einfach zu bedienen

Senden Sie Studio 13.0.1

Senden Sie Studio 13.0.1

Leistungsstarke integrierte PHP-Entwicklungsumgebung

Dreamweaver CS6

Dreamweaver CS6

Visuelle Webentwicklungstools

SublimeText3 Mac-Version

SublimeText3 Mac-Version

Codebearbeitungssoftware auf Gottesniveau (SublimeText3)

Was halten Sie von Furmark? - Wie wird Furmark als qualifiziert angesehen? Was halten Sie von Furmark? - Wie wird Furmark als qualifiziert angesehen? Mar 19, 2024 am 09:25 AM

Was halten Sie von Furmark? 1. Stellen Sie den „Ausführungsmodus“ und den „Anzeigemodus“ in der Hauptoberfläche ein, passen Sie auch den „Testmodus“ an und klicken Sie auf die Schaltfläche „Start“. 2. Nach einer Weile sehen Sie die Testergebnisse, darunter verschiedene Parameter der Grafikkarte. Wie wird Furmark qualifiziert? 1. Verwenden Sie eine Furmark-Backmaschine und überprüfen Sie das Ergebnis etwa eine halbe Stunde lang. Die Temperatur liegt im Wesentlichen bei etwa 85 Grad, mit einem Spitzenwert von 87 Grad und einer Raumtemperatur von 19 Grad. Großes Gehäuse, 5 Gehäuselüfteranschlüsse, zwei vorne, zwei oben und einer hinten, aber nur ein Lüfter ist installiert. Sämtliches Zubehör ist nicht übertaktet. 2. Unter normalen Umständen sollte die normale Temperatur der Grafikkarte zwischen „30-85℃“ liegen. 3. Auch wenn die Umgebungstemperatur im Sommer zu hoch ist, beträgt die normale Temperatur „50-85℃“

Nehmen Sie an einem neuen Xianxia-Abenteuer teil! Der Vorab-Download von „Zhu Xian 2' „Wuwei Test' ist jetzt verfügbar Nehmen Sie an einem neuen Xianxia-Abenteuer teil! Der Vorab-Download von „Zhu Xian 2' „Wuwei Test' ist jetzt verfügbar Apr 22, 2024 pm 12:50 PM

Der „Inaction Test“ des neuen Fantasy-Märchen-MMORPG „Zhu Xian 2“ startet am 23. April. Was für eine neue Märchen-Abenteuergeschichte wird auf dem Kontinent Zhu Die Six Realm Immortal World, eine Vollzeitakademie zur Kultivierung von Unsterblichen, ein freies Leben zur Kultivierung von Unsterblichen und jede Menge Spaß in der Welt der Unsterblichen warten darauf, von den unsterblichen Freunden persönlich erkundet zu werden! Der Vorab-Download von „Wuwei Test“ ist jetzt möglich. Sie können sich zum Herunterladen auf die offizielle Website begeben. Der Aktivierungscode kann nach dem Vorab-Download und der Installation verwendet werden abgeschlossen. „Zhu Als Blaupause wird der Spielhintergrund festgelegt

PHP und Vue: eine perfekte Kombination von Front-End-Entwicklungstools PHP und Vue: eine perfekte Kombination von Front-End-Entwicklungstools Mar 16, 2024 pm 12:09 PM

PHP und Vue: eine perfekte Kombination von Front-End-Entwicklungstools In der heutigen Zeit der rasanten Entwicklung des Internets ist die Front-End-Entwicklung immer wichtiger geworden. Da Benutzer immer höhere Anforderungen an das Erlebnis von Websites und Anwendungen stellen, müssen Frontend-Entwickler effizientere und flexiblere Tools verwenden, um reaktionsfähige und interaktive Schnittstellen zu erstellen. Als zwei wichtige Technologien im Bereich der Front-End-Entwicklung können PHP und Vue.js in Kombination als perfekte Waffe bezeichnet werden. In diesem Artikel geht es um die Kombination von PHP und Vue sowie um detaillierte Codebeispiele, die den Lesern helfen sollen, diese beiden besser zu verstehen und anzuwenden

Häufig gestellte Fragen von Front-End-Interviewern Häufig gestellte Fragen von Front-End-Interviewern Mar 19, 2024 pm 02:24 PM

In Front-End-Entwicklungsinterviews decken häufige Fragen ein breites Themenspektrum ab, darunter HTML/CSS-Grundlagen, JavaScript-Grundlagen, Frameworks und Bibliotheken, Projekterfahrung, Algorithmen und Datenstrukturen, Leistungsoptimierung, domänenübergreifende Anfragen, Front-End-Engineering, Designmuster sowie neue Technologien und Trends. Interviewerfragen sollen die technischen Fähigkeiten, die Projekterfahrung und das Verständnis des Kandidaten für Branchentrends beurteilen. Daher sollten Kandidaten in diesen Bereichen umfassend vorbereitet sein, um ihre Fähigkeiten und Fachkenntnisse unter Beweis zu stellen.

Was sind die Unterschiede zwischen Funktionstests und Abdeckung in verschiedenen Sprachen? Was sind die Unterschiede zwischen Funktionstests und Abdeckung in verschiedenen Sprachen? Apr 27, 2024 am 11:30 AM

Funktionstests überprüfen die Funktionsfunktionalität durch Black-Box- und White-Box-Tests, während die Codeabdeckung den Teil des Codes misst, der von Testfällen abgedeckt wird. Verschiedene Sprachen (wie Python und Java) verfügen über unterschiedliche Test-Frameworks, Abdeckungstools und Funktionen. Praktische Fälle zeigen, wie man Unittest und Coverage von Python sowie JUnit und JaCoCo von Java für Funktionstests und Coverage-Bewertung verwendet.

Ist Django Front-End oder Back-End? Hör zu! Ist Django Front-End oder Back-End? Hör zu! Jan 19, 2024 am 08:37 AM

Django ist ein in Python geschriebenes Webanwendungs-Framework, das Wert auf schnelle Entwicklung und saubere Methoden legt. Obwohl Django ein Web-Framework ist, müssen Sie zur Beantwortung der Frage, ob Django ein Front-End oder ein Back-End ist, ein tiefes Verständnis der Konzepte von Front-End und Back-End haben. Das Front-End bezieht sich auf die Schnittstelle, mit der Benutzer direkt interagieren, und das Back-End bezieht sich auf serverseitige Programme. Sie interagieren mit Daten über das HTTP-Protokoll. Wenn das Front-End und das Back-End getrennt sind, können die Front-End- und Back-End-Programme unabhängig voneinander entwickelt werden, um Geschäftslogik bzw. interaktive Effekte sowie den Datenaustausch zu implementieren.

Der neue König der heimischen FPS! „Operation Delta' Battlefield übertrifft Erwartungen Der neue König der heimischen FPS! „Operation Delta' Battlefield übertrifft Erwartungen Mar 07, 2024 am 09:37 AM

„Operation Delta“ wird heute (7. März) einen groß angelegten PC-Test mit dem Namen „Codename: ZERO“ starten. Letztes Wochenende veranstaltete dieses Spiel in Shanghai eine Offline-Flashmob-Erlebnisveranstaltung, und 17173 hatte auch das Glück, zur Teilnahme eingeladen zu werden. Dieser Test liegt etwas mehr als vier Monate seit dem letzten Test zurück, was uns neugierig macht, welche neuen Highlights und Überraschungen wird „Operation Delta“ in so kurzer Zeit mit sich bringen? Vor mehr als vier Monaten habe ich „Operation Delta“ in einer Offline-Verkostung und der ersten Beta-Version erlebt. Damals öffnete das Spiel nur den „Dangerous Action“-Modus. Allerdings war die Operation Delta für ihre Zeit bereits beeindruckend. Im Kontext der großen Hersteller, die in den Markt für mobile Spiele strömen, ist ein solcher FPS mit internationalen Standards vergleichbar

Was ist ein modulares Front-End-ESM? Was ist ein modulares Front-End-ESM? Feb 25, 2024 am 11:48 AM

Was ist Front-End-ESM? Spezifische Codebeispiele sind erforderlich. Bei der Front-End-Entwicklung bezieht sich ESM auf ECMAScriptModules, eine modulare Entwicklungsmethode, die auf der ECMAScript-Spezifikation basiert. ESM bietet viele Vorteile, wie z. B. eine bessere Codeorganisation, Isolierung zwischen Modulen und Wiederverwendbarkeit. In diesem Artikel werden die grundlegenden Konzepte und die Verwendung von ESM vorgestellt und einige spezifische Codebeispiele bereitgestellt. Das Grundkonzept von ESM In ESM können wir den Code in mehrere Module unterteilen, und jedes Modul stellt einige Schnittstellen für andere Module bereit

See all articles