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

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.

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

Kemudian, pasang Koa2 dan yang berkaitan dependencies:

npm install koa koa-router --save

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

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;

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.

Menulis antara muka API

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;

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下的接口
    */

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
    */

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'
   */

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

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

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!