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

AI Hentai Generator

AI Hentai Generator

Menjana ai hentai secara percuma.

Artikel Panas

R.E.P.O. Kristal tenaga dijelaskan dan apa yang mereka lakukan (kristal kuning)
2 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌
Repo: Cara menghidupkan semula rakan sepasukan
4 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island Adventure: Cara mendapatkan biji gergasi
4 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌

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℃"

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

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.

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.

Apakah perbezaan antara ujian fungsi dan liputan dalam bahasa yang berbeza? Apakah perbezaan antara ujian fungsi dan liputan dalam bahasa yang berbeza? Apr 27, 2024 am 11:30 AM

Ujian fungsional mengesahkan kefungsian fungsi melalui ujian kotak hitam dan kotak putih, manakala liputan kod mengukur bahagian kod yang diliputi oleh kes ujian. Bahasa yang berbeza (seperti Python dan Java) mempunyai rangka kerja ujian, alat liputan dan ciri yang berbeza. Kes praktikal menunjukkan cara menggunakan Unittest and Coverage Python dan JUnit dan JaCoCo Java untuk ujian fungsi dan penilaian liputan.

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.

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

Apakah ESM modular bahagian hadapan? Apakah ESM modular bahagian hadapan? Feb 25, 2024 am 11:48 AM

Apakah itu ESM bahagian hadapan? Contoh kod khusus diperlukan Dalam pembangunan bahagian hadapan, ESM merujuk kepada ECMAScriptModules, kaedah pembangunan modular berdasarkan spesifikasi ECMAScript. ESM membawa banyak faedah, seperti organisasi kod yang lebih baik, pengasingan antara modul dan kebolehgunaan semula. Artikel ini akan memperkenalkan konsep asas dan penggunaan ESM dan menyediakan beberapa contoh kod khusus. Konsep asas ESM Dalam ESM, kita boleh membahagikan kod kepada berbilang modul, dan setiap modul mendedahkan beberapa antara muka untuk modul lain kepada

See all articles