기사에서는 Koa2를 사용하여 Node.js 프로젝트에 Swagger를 통합하는 방법을 설명합니다.-JS 튜토리얼-php.cn

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

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

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(&#39;swagger-jsdoc&#39;);
const options = {
    definition: {
        openapi: &#39;3.0.0&#39;,
        info: {
            title: &#39;我是标题&#39;,
            version: &#39;1.0.0&#39;,
            description: &#39;我是描述&#39;,
        },
        //servers的每一项，可以理解为一个服务,实际项目中，可自由修改
        servers: [
            {
                url: &#39;/api&#39;,
                description: &#39;API server&#39;,
            },
        ],
    },
    apis: [&#39;./routes/*.js&#39;],
};

const swaggerSpec = swaggerJSDoc(options);

// 如果有Swagger规范文件转TS的需求，可在此处保留Swagger规范文件到本地，方便使用
//fs.writeFileSync(&#39;swagger.json&#39;, JSON.stringify(swaggerSpec, null, 2));

module.exports = swaggerSpec;

로그인 후 복사

这里，我们定义了一个名为options的对象，包含了Swagger的基本信息和API接口的来源（即我们的路由文件）。然后，我们使用swagger-jsdoc生成API文档，并将其导出。

编写API接口

现在，我们来创建一个名为routes的文件夹，并在其中创建一个名为users.js的文件，用于定义用户相关的API接口。在users.js文件中，我们将编写以下代码：

const Router = require(&#39;koa-router&#39;);
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&#39;s name.
*         email:
*           type: string
*           description: The user&#39;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: &#39;#/components/schemas/User&#39;
*/
router.get(&#39;/users&#39;, async (ctx) => {
    const users = [
        { id: 1, name: &#39;John Doe&#39;, email: &#39;john.doe@example.com&#39; },
        { id: 2, name: &#39;Jane Doe&#39;, email: &#39;jane.doe@example.com&#39; },
    ];
    ctx.body = users;
});

module.exports = router;

로그인 후 복사

注释简析：

tags：这部分定义了一个名为"Users"的标签。标签用于对API接口进行分类和分组。在这里，标签名为"Users"，描述为"users.js下的接口"。
```
/**
 * @swagger
 * tags:
 *   name: Users
 *   description: users.js下的接口
 */
```
로그인 후 복사
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
 */
```
로그인 후 복사
/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: &#39;#/components/schemas/User&#39;
*/
```
로그인 후 복사
Swagger 구성

swagger.js

const Koa = require(&#39;koa&#39;);
const Router = require(&#39;koa-router&#39;);
const swaggerUI = require(&#39;koa2-swagger-ui&#39;).koaSwagger;
const swaggerSpec = require(&#39;./swagger&#39;);
const usersRoutes = require(&#39;./routes/users&#39;);

const app = new Koa();
const router = new Router();

router.use(&#39;/api&#39;, usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    &#39;/swagger&#39;,
    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

GET

200

application/json

$ref: '#/comComponents/schemas/User'

comComponents

스키마

사용자

요약

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