기사에서는 Koa2를 사용하여 Node.js 프로젝트에 Swagger를 통합하는 방법을 설명합니다.

이 기사에서는 Koa2를 사용하여 Node.js 프로젝트에 Swagger를 통합하여 API 문서를 자동으로 생성하는 방법을 살펴보겠습니다. Swagger의 기본 개념과 관련 NPM 패키지를 소개하고 자세한 코드 예제와 설명을 통해 전체 프로세스를 보여줍니다.

Swagger란 무엇입니까

Swagger는 개발자가 API 문서를 빠르고 정확하게 작성, 유지 관리 및 검토하는 데 도움이 되는 RESTful API 문서 생성 도구입니다. Swagger에는 다음과 같은 장점이 있습니다.

• API 문서를 자동으로 생성하여 수동 작성 작업량을 줄입니다.
• 디버깅 및 검증을 용이하게 하는 시각적 API 인터페이스 테스트 도구를 제공합니다.
• 여러 언어와 프레임워크를 지원하며 다양성과 확장성이 뛰어납니다.

Koa2 프로젝트 만들기

먼저 Koa2를 기반으로 Node.js 프로젝트를 만들어야 합니다. 다음 명령을 사용하여 프로젝트를 만들 수 있습니다. [관련 튜토리얼 권장 사항: nodejs video tutorial, Programming Teaching]

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

그런 다음 Koa2 및 관련 종속성을 설치합니다.

npm install koa koa-router --save

Swagger 관련 종속성을 설치합니다

다음으로 우리는 Swagger 관련 NPM 패키지를 설치해야 합니다. 이 튜토리얼에서는 koa2-swagger-ui와 swagger-jsdoc를 사용합니다. Swagger UI를 표시하고 API 문서를 생성하는 데 각각 사용됩니다. 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 구성

프로젝트 루트 디렉터리에서 Swagger 구성을 위한 swagger.js라는 파일을 만듭니다. 구성 코드는 다음과 같습니다.

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

여기서 Swagger의 기본 정보와 API 인터페이스 소스(즉, 라우팅 파일)가 포함된 options라는 개체를 정의합니다. 그런 다음 swagger-jsdoc

API 문서를 생성하고 내보냅니다.

API 인터페이스 작성

이제 routes라는 폴더를 만들고 그 안에 users라는 폴더를 만들어 보겠습니다. 사용자 관련 API 인터페이스를 정의하는 데 사용되는 파일입니다. users.js 파일에 다음 코드를 작성합니다:

node app.js

댓글 분석:

tags: 섹션은 "사용자"라는 레이블을 정의합니다. 태그는 API 인터페이스를 분류하고 그룹화하는 데 사용됩니다. 여기서 레이블 이름은 "Users"이고 설명은 "Users.js 아래 인터페이스"입니다.

rrreee

구성 요소 및 스키마: 이 부분은 "User"라는 데이터 모델을 정의합니다. 데이터 모델은 API 인터페이스에 사용되는 데이터 구조를 설명합니다. 이 예에서 "User" 모델에는 id(정수 유형, 사용자 ID를 나타냄), name(문자열 유형, 사용자 이름을 나타냄) 및 의 세 가지 속성이 포함되어 있습니다. email (사용자의 이메일을 나타내는 문자열 유형). 동시에 id, name 및 email 속성은 필수로 표시됩니다. rrreee

🎜🎜/users API 인터페이스: 이 부분은 사용자 목록을 얻기 위한 API 인터페이스를 정의합니다. /users 경로를 사용하여 GET 요청을 설명합니다. 이 인터페이스는 이전에 정의된 "사용자" 태그를 사용합니다. 또한 200 상태 코드로 성공적인 응답을 정의하여 사용자 목록이 반환되었음을 나타냅니다. 응답의 콘텐츠 유형은 application/json이고 해당 구조는 "User" 모델을 포함하는 배열입니다. 🎜🎜$ref: '#/comComponents/schemas/User'는 이전에 comComponents A 아래에 정의된 스키마를 참조하는 참조 구문입니다. 사용자라는 데이터 모델. 🎜rrreee🎜🎜🎜이 코드는 사용자 관리 인터페이스, 데이터 모델 및 응답 형식에 대한 세부정보가 포함된 API 문서를 제공합니다. Swagger JSDoc은 이러한 주석을 구문 분석하고 해당 OpenAPI 문서를 생성합니다. 🎜🎜API 문서 생성🎜🎜다음으로 프로젝트에서 Swagger UI를 활성화해야 합니다. 프로젝트 루트 디렉터리에 app.js라는 파일을 생성하고 다음 코드를 작성합니다. 🎜rrreee🎜여기에서는 koa2-swagger-ui 및 swagger-jsdoc에서 생성된 API 문서를 가져왔습니다. 그런 다음 Swagger UI를 표시하기 위해 /swagger라는 경로를 정의했습니다. 마지막으로 사용자 관련 API 인터페이스를 /api 경로에 마운트합니다. 🎜🎜Test🎜rrreee🎜Open 🎜http://localhost:3000/swagger🎜 Swagger UI와 자동으로 생성된 API 문서가 표시됩니다. 🎜

요약

이 글에서는 Koa2 기반 Node.js 프로젝트에서 Swagger를 통합하고 API 문서를 자동으로 생성하는 방법을 자세히 소개했습니다. koa2-swagger-ui 및 swagger-jsdoc를 사용하면 API 인터페이스에 대한 온라인 문서를 쉽게 생성하고 Swagger UI를 시각적 테스트에 활용할 수 있습니다.

Swagger를 통합하는 주요 단계는 다음과 같습니다.

• 관련 종속성 설치: koa2-swagger-ui 및 swagger-jsdoc
• Swagger 구성: swagger.js 파일 생성, API의 기본 정보 및 인터페이스 소스 정의 문서
• API 인터페이스 작성: Swagger 주석 구문을 사용하여 인터페이스 정보 설명
• Swagger UI 활성화: app.js에서 Swagger UI 경로를 구성하고 API 문서를 전달합니다.
• 프로젝트 실행 및 Swagger UI에 액세스

위 단계를 통해 프로젝트에서 API 문서의 자동 생성, 업데이트, 검토를 구현하여 개발 효율성과 협업 효과를 높일 수 있습니다. 동시에 Swagger UI에서 제공하는 테스트 도구를 사용하여 API 인터페이스의 정확성과 안정성을 쉽게 확인할 수도 있습니다.

Swagger 사양 파일은 swagger-to-ts를 사용하여 TypeScript 유형 파일로 변환할 수 있습니다.

노드 관련 지식을 더 보려면 nodejs 튜토리얼을 방문하세요!

위 내용은 기사에서는 Koa2를 사용하여 Node.js 프로젝트에 Swagger를 통합하는 방법을 설명합니다.의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!