Jadual Kandungan
Apakah itu Swagger
Mencipta projek Koa2
Pasang dependencies berkaitan Swagger
Mengkonfigurasi Swagger
Menulis antara muka API
Komen analisis ringkas:
Jana dokumentasi API
Ujian
Ringkasan
Rumah hujung hadapan web tutorial js Satu artikel membincangkan cara menggunakan Koa2 untuk menyepadukan Swagger dalam projek Node.js

Satu artikel membincangkan cara menggunakan Koa2 untuk menyepadukan Swagger dalam projek Node.js

Apr 01, 2023 am 07:30 AM
hujung hadapan node.js ujian

Dalam artikel ini, kami akan meneroka cara menggunakan Koa2 untuk menyepadukan Swagger dalam projek Node.js untuk menjana dokumentasi API secara automatik. Kami akan memperkenalkan konsep asas Swagger, pakej NPM yang berkaitan, dan menunjukkan keseluruhan proses dengan contoh dan penjelasan kod terperinci.

Satu artikel membincangkan cara menggunakan Koa2 untuk menyepadukan Swagger dalam projek Node.js

Apakah itu Swagger

Swagger ialah alat penjanaan dokumen API RESTful yang boleh membantu pembangun menulis, menyelenggara dan menyemak dokumen API dengan cepat dan tepat. Swagger mempunyai kelebihan berikut:

  • Menjana dokumen API secara automatik, mengurangkan beban kerja penulisan manual
  • Sediakan alat ujian antara muka API visual untuk memudahkan penyahpepijatan dan pengesahan
  • Sokongan Pelbagai bahasa dan rangka kerja, dengan kepelbagaian dan kebolehskalaan yang baik

Mencipta projek Koa2

Pertama, kita perlu mencipta projek Node.js berdasarkan Koa2. Anda boleh menggunakan arahan berikut untuk mencipta projek: [Cadangan tutorial berkaitan: tutorial video nodejs, Pengajaran pengaturcaraan]

mkdir koa2-swagger-demo
cd koa2-swagger-demo
npm init -y
Salin selepas log masuk

Kemudian, pasang Koa2 dan yang berkaitan dependencies:

npm install koa koa-router --save
Salin selepas log masuk

Pasang dependencies berkaitan Swagger

Seterusnya, kita perlu memasang pakej NPM berkaitan Swagger. Dalam tutorial ini, kami akan menggunakan koa2-swagger-ui dan swagger-jsdoc. Digunakan untuk memaparkan UI Swagger dan menjana dokumentasi API masing-masing.

npm install koa2-swagger-ui swagger-jsdoc --save
Salin selepas log masuk

Mengkonfigurasi Swagger

Dalam direktori akar projek, cipta fail bernama swagger.js untuk mengkonfigurasi Swagger. Kod konfigurasi adalah seperti berikut:

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;
Salin selepas log masuk

Di sini, kami mentakrifkan objek bernama options, yang mengandungi maklumat asas Swagger dan sumber antara muka API (iaitu, fail penghalaan kami). Kemudian, kami menggunakan swagger-jsdoc untuk menjana dokumentasi API dan mengeksportnya.

Sekarang, mari buat folder bernama routes dan fail bernama users.js di dalamnya untuk menentukan antara muka API berkaitan pengguna. Dalam fail users.js, kami akan menulis kod berikut:

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;
Salin selepas log masuk

Komen analisis ringkas:

  1. tags: Bahagian ini mentakrifkan fail yang dipanggil " Tag pengguna". Teg digunakan untuk mengelaskan dan mengumpulkan antara muka API. Di sini, label dinamakan "Pengguna" dan keterangannya ialah "Antaramuka di bawah pengguna.js".

    /**
     * @swagger
     * tags:
     *   name: Users
     *   description: users.js下的接口
     */
    Salin selepas log masuk
  2. components dan schemas: Bahagian ini mentakrifkan model data bernama "Pengguna". Model data menerangkan struktur data yang digunakan dalam antara muka API. Dalam contoh ini, model "Pengguna" mengandungi tiga atribut: id (jenis integer, mewakili ID pengguna), name (jenis rentetan, mewakili nama pengguna) dan email (jenis rentetan, mewakili mel elektronik pengguna) mel ). Pada masa yang sama, atribut id, name dan email semuanya ditandakan seperti yang diperlukan.

    /**
     * @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
     */
    Salin selepas log masuk
  3. /users Antara muka API: Bahagian ini mentakrifkan antara muka API untuk mendapatkan senarai pengguna. Ia menerangkan permintaan GET dengan laluan /users. Antara muka ini menggunakan teg "Pengguna" yang ditakrifkan sebelum ini. Selain itu, ia juga mentakrifkan respons yang berjaya dengan kod status 200, yang menunjukkan bahawa senarai pengguna dikembalikan. Jenis kandungan respons ialah application/json dan strukturnya ialah tatasusunan yang mengandungi model "Pengguna".

    $ref: '#/components/schemas/User' ialah sintaks rujukan yang merujuk kepada model data bernama components dalam schemas yang ditakrifkan sebelum ini di bawah User.

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

Kod ini menyediakan dokumentasi API dengan butiran tentang antara muka pengurusan pengguna, model data dan format respons. Swagger JSDoc menghuraikan anotasi ini dan menjana dokumen OpenAPI yang sepadan.

Jana dokumentasi API

Seterusnya, kami perlu mendayakan Swagger UI dalam projek. Dalam direktori akar projek, buat fail bernama app.js dan tulis kod berikut:

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}`);
});
Salin selepas log masuk

Di sini, kami mengimport dokumentasi API yang dijana oleh koa2-swagger-ui dan swagger-jsdoc. Kemudian, kami menentukan laluan bernama /swagger untuk memaparkan UI Swagger. Akhir sekali, kami memasang antara muka API berkaitan pengguna ke laluan /api.

Ujian

node app.js
Salin selepas log masuk

Buka http://localhost:3000/swagger dalam penyemak imbas anda Anda akan melihat UI Swagger dan dokumentasi API yang dijana secara automatik.

Ringkasan

Dalam artikel ini, kami memperkenalkan secara terperinci cara menyepadukan Swagger dan menjana dokumentasi API secara automatik dalam projek Node.js berdasarkan Koa2. Dengan menggunakan koa2-swagger-ui dan swagger-jsdoc, kami boleh menjana dokumentasi dalam talian dengan mudah untuk antara muka API dan menggunakan UI Swagger untuk ujian visual.

Langkah utama untuk mengintegrasikan Swagger adalah seperti berikut:

  • Pasang kebergantungan berkaitan: koa2-swagger-ui dan swagger-jsdoc
  • Konfigurasikan Swagger: cipta swagger Fail .js, Tentukan maklumat asas dan sumber antara muka dokumen API
  • Tulis antara muka API: gunakan sintaks anotasi Swagger untuk menerangkan maklumat antara muka
  • Dayakan Swagger UI: konfigurasikan penghalaan Swagger UI dalam app.js dan tambahkan Dokumen API dihantar kepadanya
  • Jalankan projek dan akses Swagger UI

Melalui langkah di atas, kami boleh menjana, mengemas kini dan menyemak API secara automatik dokumen dalam projek, dengan itu meningkatkan kecekapan pembangunan dan kesan kerjasama. Pada masa yang sama, menggunakan alat ujian yang disediakan oleh Swagger UI, kami juga boleh mengesahkan ketepatan dan kestabilan antara muka API dengan mudah.

Anda boleh menggunakan swagger-to-ts untuk menukar fail spesifikasi Swagger kepada fail jenis TypeScript.

Untuk lebih banyak pengetahuan berkaitan nod, sila lawati: tutorial nodejs!

Atas ialah kandungan terperinci Satu artikel membincangkan cara menggunakan Koa2 untuk menyepadukan Swagger dalam projek Node.js. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!

Kenyataan Laman Web ini
Kandungan artikel ini disumbangkan secara sukarela oleh netizen, dan hak cipta adalah milik pengarang asal. Laman web ini tidak memikul tanggungjawab undang-undang yang sepadan. Jika anda menemui sebarang kandungan yang disyaki plagiarisme atau pelanggaran, sila hubungi admin@php.cn

Alat AI Hot

Undresser.AI Undress

Undresser.AI Undress

Apl berkuasa AI untuk mencipta foto bogel yang realistik

AI Clothes Remover

AI Clothes Remover

Alat AI dalam talian untuk mengeluarkan pakaian daripada foto.

Undress AI Tool

Undress AI Tool

Gambar buka pakaian secara percuma

Clothoff.io

Clothoff.io

Penyingkiran pakaian AI

Video Face Swap

Video Face Swap

Tukar muka dalam mana-mana video dengan mudah menggunakan alat tukar muka AI percuma kami!

Alat panas

Notepad++7.3.1

Notepad++7.3.1

Editor kod yang mudah digunakan dan percuma

SublimeText3 versi Cina

SublimeText3 versi Cina

Versi Cina, sangat mudah digunakan

Hantar Studio 13.0.1

Hantar Studio 13.0.1

Persekitaran pembangunan bersepadu PHP yang berkuasa

Dreamweaver CS6

Dreamweaver CS6

Alat pembangunan web visual

SublimeText3 versi Mac

SublimeText3 versi Mac

Perisian penyuntingan kod peringkat Tuhan (SublimeText3)

Apakah pendapat anda tentang furmark - Bagaimanakah furmark dianggap layak? Apakah pendapat anda tentang furmark - Bagaimanakah furmark dianggap layak? Mar 19, 2024 am 09:25 AM

Apakah pendapat anda tentang furmark? 1. Tetapkan "Mod Jalankan" dan "Mod Paparan" dalam antara muka utama, dan juga laraskan "Mod Ujian" dan klik butang "Mula". 2. Selepas menunggu seketika, anda akan melihat keputusan ujian, termasuk pelbagai parameter kad grafik. Bagaimanakah furmark layak? 1. Gunakan mesin pembakar furmark dan semak hasilnya selama kira-kira setengah jam Ia pada asasnya berlegar sekitar 85 darjah, dengan puncak 87 darjah dan suhu bilik 19 darjah. Casis besar, 5 port kipas casis, dua di hadapan, dua di atas, dan satu di belakang, tetapi hanya satu kipas dipasang. Semua aksesori tidak overclock. 2. Dalam keadaan biasa, suhu biasa kad grafik hendaklah antara "30-85℃". 3. Walaupun suhu ambien terlalu tinggi pada musim panas, suhu biasa ialah "50-85℃"

PHP dan Vue: gandingan sempurna alat pembangunan bahagian hadapan PHP dan Vue: gandingan sempurna alat pembangunan bahagian hadapan Mar 16, 2024 pm 12:09 PM

PHP dan Vue: gandingan sempurna alat pembangunan bahagian hadapan Dalam era perkembangan pesat Internet hari ini, pembangunan bahagian hadapan telah menjadi semakin penting. Memandangkan pengguna mempunyai keperluan yang lebih tinggi dan lebih tinggi untuk pengalaman tapak web dan aplikasi, pembangun bahagian hadapan perlu menggunakan alat yang lebih cekap dan fleksibel untuk mencipta antara muka yang responsif dan interaktif. Sebagai dua teknologi penting dalam bidang pembangunan bahagian hadapan, PHP dan Vue.js boleh dianggap sebagai alat yang sempurna apabila digandingkan bersama. Artikel ini akan meneroka gabungan PHP dan Vue, serta contoh kod terperinci untuk membantu pembaca memahami dan menggunakan kedua-dua ini dengan lebih baik.

Sertai pengembaraan Xianxia baharu! Pramuat turun 'Zhu Xian 2' 'Wuwei Test' kini tersedia Sertai pengembaraan Xianxia baharu! Pramuat turun 'Zhu Xian 2' 'Wuwei Test' kini tersedia Apr 22, 2024 pm 12:50 PM

"Ujian Inaction" bagi MMORPG dongeng fantasi baharu "Zhu Xian 2" akan dilancarkan pada 23 April. Apakah jenis kisah pengembaraan dongeng baharu yang akan berlaku di Benua Zhu Xian beribu-ribu tahun selepas karya asal? The Six Realm Immortal World, akademi abadi sepenuh masa, kehidupan abadi percuma, dan semua jenis keseronokan di dunia abadi sedang menunggu rakan-rakan abadi untuk meneroka secara peribadi! Pra-muat turun "Wuwei Test" kini dibuka Rakan-rakan Fairy boleh pergi ke laman web rasmi untuk memuat turun Anda tidak boleh log masuk ke pelayan permainan sebelum pelayan dilancarkan sudah selesai. Waktu pembukaan "Zhu Xian 2" "Inaction Test": 23 April 10:00 - 6 Mei 23:59 Bab pengembaraan dongeng baharu sekuel ortodoks kepada Zhu Xian "Zhu Xian 2" adalah berdasarkan novel "Zhu Xian" sebagai cetak biru Berdasarkan pandangan dunia karya asal, latar belakang permainan ditetapkan

Raja baharu FPS domestik! Medan Perang 'Operasi Delta' Melebihi Jangkaan Raja baharu FPS domestik! Medan Perang 'Operasi Delta' Melebihi Jangkaan Mar 07, 2024 am 09:37 AM

"Operation Delta" akan melancarkan ujian PC berskala besar yang dipanggil "Codename: ZERO" hari ini (7 Mac). Hujung minggu lalu, permainan ini mengadakan acara pengalaman flash mob luar talian di Shanghai, dan 17173 juga bertuah kerana dijemput untuk mengambil bahagian. Ujian ini hanya tinggal lebih empat bulan lagi daripada kali terakhir, yang membuatkan kami tertanya-tanya, apakah sorotan dan kejutan baharu yang akan dibawa oleh "Operasi Delta" dalam tempoh yang singkat? Lebih empat bulan yang lalu, saya mengalami "Operasi Delta" dalam sesi merasa luar talian dan versi beta pertama. Pada masa itu, permainan hanya membuka mod "Tindakan Berbahaya". Walau bagaimanapun, Operasi Delta sudah mengagumkan pada zamannya. Dalam konteks pengeluar utama yang berpusu-pusu ke pasaran permainan mudah alih, FPS sedemikian yang setanding dengan piawaian antarabangsa

Soalan yang sering ditanya oleh penemuduga front-end Soalan yang sering ditanya oleh penemuduga front-end Mar 19, 2024 pm 02:24 PM

Dalam temu bual pembangunan bahagian hadapan, soalan lazim merangkumi pelbagai topik, termasuk asas HTML/CSS, asas JavaScript, rangka kerja dan perpustakaan, pengalaman projek, algoritma dan struktur data, pengoptimuman prestasi, permintaan merentas domain, kejuruteraan bahagian hadapan, corak reka bentuk, dan teknologi dan trend baharu. Soalan penemuduga direka bentuk untuk menilai kemahiran teknikal calon, pengalaman projek dan pemahaman tentang trend industri. Oleh itu, calon harus bersedia sepenuhnya dalam bidang ini untuk menunjukkan kebolehan dan kepakaran mereka.

Adakah Django bahagian hadapan atau belakang? semaklah! Adakah Django bahagian hadapan atau belakang? semaklah! Jan 19, 2024 am 08:37 AM

Django ialah rangka kerja aplikasi web yang ditulis dalam Python yang menekankan pembangunan pesat dan kaedah bersih. Walaupun Django ialah rangka kerja web, untuk menjawab soalan sama ada Django ialah front-end atau back-end, anda perlu mempunyai pemahaman yang mendalam tentang konsep front-end dan back-end. Bahagian hadapan merujuk kepada antara muka yang pengguna berinteraksi secara langsung, dan bahagian belakang merujuk kepada program bahagian pelayan Mereka berinteraksi dengan data melalui protokol HTTP. Apabila bahagian hadapan dan bahagian belakang dipisahkan, program bahagian hadapan dan bahagian belakang boleh dibangunkan secara bebas untuk melaksanakan logik perniagaan dan kesan interaktif masing-masing, dan pertukaran data.

Meneroka teknologi bahagian hadapan bahasa Go: visi baharu untuk pembangunan bahagian hadapan Meneroka teknologi bahagian hadapan bahasa Go: visi baharu untuk pembangunan bahagian hadapan Mar 28, 2024 pm 01:06 PM

Sebagai bahasa pengaturcaraan yang pantas dan cekap, bahasa Go popular secara meluas dalam bidang pembangunan bahagian belakang. Walau bagaimanapun, beberapa orang mengaitkan bahasa Go dengan pembangunan bahagian hadapan. Malah, menggunakan bahasa Go untuk pembangunan bahagian hadapan bukan sahaja boleh meningkatkan kecekapan, tetapi juga membawa ufuk baharu kepada pembangun. Artikel ini akan meneroka kemungkinan menggunakan bahasa Go untuk pembangunan bahagian hadapan dan memberikan contoh kod khusus untuk membantu pembaca memahami dengan lebih baik bahagian ini. Dalam pembangunan front-end tradisional, JavaScript, HTML dan CSS sering digunakan untuk membina antara muka pengguna

Bagaimana untuk melumpuhkan kes ujian di Maven? Bagaimana untuk melumpuhkan kes ujian di Maven? Feb 26, 2024 am 09:57 AM

Maven ialah alat pengurusan projek sumber terbuka yang biasa digunakan untuk tugas seperti membina projek Java, mengurus kebergantungan dan menerbitkan dokumen. Apabila menggunakan Maven untuk binaan projek, kadangkala kita mahu mengabaikan fasa ujian apabila melaksanakan arahan seperti mvnpackage, yang akan meningkatkan kelajuan binaan dalam beberapa kes, terutamanya apabila prototaip atau persekitaran ujian perlu dibina dengan cepat. Artikel ini akan memperincikan cara mengabaikan fasa ujian dalam Maven, dengan contoh kod tertentu. Mengapa Ujian Sering Diabaikan Semasa Pembangunan Projek

See all articles