# @deadendjs/swagger-jsdoc 中文文档

规范地址：https://npmcn.com/package/%40deadendjs/swagger-jsdoc/

版本：8\.2\.0
npm 元数据更新时间：2026-04-27T12:47:03.833Z
中文译文更新时间：2026-11-11T18:23:50.588Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deadendjs/swagger-jsdoc
原文对照：https://npmcn.com/package/%40deadendjs/swagger-jsdoc/?lang=original
项目主页：https://github.com/deadendjs/swagger-jsdoc
源码仓库：https://github.com/deadendjs/swagger-jsdoc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：31.5 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- 首次发布：2025-10-30T09:06:47.461Z
- 最新版本发布：2026-04-27T12:47:03.704Z
- 近 30 天下载量：10520（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 4 个）

## 中文简介

基于 JSDoc 生成 swagger doc

## 安装

```sh
npm install @deadendjs/swagger-jsdoc
```

也可以使用：`pnpm add @deadendjs/swagger-jsdoc`、`yarn add @deadendjs/swagger-jsdoc`、`bun add @deadendjs/swagger-jsdoc`

## README

# 斯瓦格 - 日记

> \[注\] 这个叉子大多是用来不断更新依赖关系,因为原来的回波已经一段时间没有活动了. 但如果你发现问题,可以自由提交带有破解测试的PR(如果是代码问题)并固定.

这个图书馆读取你的 [联合来文文件](https://jsdoc.app/)\-附加说明的源代码并生成一个 [OpenAPI (Swagger) 规格](https://swagger.io/specification/)。 。 。 .

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=deadendjs_swagger-jsdoc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=deadendjs_swagger-jsdoc) ![CI](https://github.com/deadendjs/swagger-jsdoc/workflows/CI/badge.svg)

## 开始

想象有这样的 API 文件:

```javascript
/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});
```

图书馆将接收 `@openapi` (或 `@swagger`),配置如下:

```javascript
const swaggerJsdoc = require('@deadendjs/swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0'
    }
  },
  apis: ['./src/routes*.js'] // files containing annotations as above
};

const openapiSpecification = await swaggerJsdoc(options);
```

结果 `openapiSpecification` 将是一个 [摇摆工具](https://swagger.io/tools/)\- 符合(并经验证)规格.

![swagger-jsdoc example screenshot](https://npmcn.com/package/%40deadendjs/swagger-jsdoc/docs/screenshot.png)

## 系统要求

-   节点.js 20.x或以上

你正在观看 `swagger-jsdoc` v8,发布于CommonJS模块系统.

## 安装

```bash
npm install @deadendjs/swagger-jsdoc --save
```

## 支持的规格

-   打开API 3.x
-   斯瓦格2号
-   AsyncAPI 2. 0 (英语)

## Swagger 文件的验证

默认 `swagger-jsdoc` 试着把所有文件都解析到最好的能力 如果您想要使用设置选项旗的验证失败, 可以指定一个错误 `failOnErrors` 改为 `true`。例如,如果您想要验证您的 swagger docs 使用单位测试进行验证,则此功能是有用的.

```javascript
const swaggerJsdoc = require('@deadendjs/swagger-jsdoc');

const options = {
  failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false.
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0'
    }
  },
  apis: ['./src/routes*.js']
};

const openapiSpecification = await swaggerJsdoc(options);
```

## 文档

[Github 页面上的文档](https://deadendjs.github.io/swagger-jsdoc/)

## 常见问题

### @deadendjs/swagger-jsdoc 是什么？

基于 JSDoc 生成 swagger doc

### 如何安装 @deadendjs/swagger-jsdoc？

在项目目录运行 npm install @deadendjs/swagger-jsdoc，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 swagger-jsdoc，可以用 npx swagger-jsdoc 直接运行。

### @deadendjs/swagger-jsdoc 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deadendjs/swagger-jsdoc 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @deadendjs/swagger-jsdoc 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deadendjs/swagger-jsdoc 可以商用吗？

@deadendjs/swagger-jsdoc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deadendjs/swagger-jsdoc 的下载量有多少？

根据 npm 官方下载统计，@deadendjs/swagger-jsdoc 在 2026/10/12 – 2026/11/10 这 30 天内被下载 10,520 次，日均约 351 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deadendjs/swagger-jsdoc 还在维护吗？

最新版本 8\.2\.0 发布于 2026/04/27（6 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 4 个；首次发布于 2025/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。