# @funboxteam/blueprinter 中文文档

规范地址：https://npmcn.com/package/%40funboxteam/blueprinter/

版本：6\.1\.0
npm 元数据更新时间：2024-02-01T13:13:47.998Z
中文译文更新时间：2026-11-15T17:08:45.564Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40funboxteam/blueprinter
原文对照：https://npmcn.com/package/%40funboxteam/blueprinter/?lang=original
项目主页：https://github.com/funbox/blueprinter#readme
源码仓库：https://github.com/funbox/blueprinter

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

- 包体积（解压后）：802 kB，12 个文件
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2022-07-13T21:09:02.818Z
- 最新版本发布：2024-02-01T13:13:47.780Z
- 近 30 天下载量：2080（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

替换用于渲染的 Aglio 库生成的 AST 作为 HTML 页面 .

## 安装

```sh
npm install @funboxteam/blueprinter
```

也可以使用：`pnpm add @funboxteam/blueprinter`、`yarn add @funboxteam/blueprinter`、`bun add @funboxteam/blueprinter`

## README

# @funboxteam/蓝印机

[![npm (scoped)](https://img.shields.io/npm/v/@funboxteam/blueprinter)](https://www.npmjs.com/package/@funboxteam/blueprinter) [![Coverage Status](https://coveralls.io/repos/github/funbox/blueprinter/badge.svg?branch=master)](https://coveralls.io/github/funbox/blueprinter?branch=master)

![Blueprinter avatar](https://npmcn.com/package/%40funboxteam/blueprinter/logo.png)

**蓝图** 是一个 [API 蓝图](https://apiblueprint.org/) 变形器。 它使用API AST的形式为: [API 元素](https://apielements.org/) 并生成带有文档的 HTML 页面.

[{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢](https://npmcn.com/package/%40funboxteam/blueprinter/README.ru.md)

## 理由

API 蓝图标准主要由 [阿皮亚里](https://apiary.io/),它拥有官方解析器 [起草者](https://github.com/apiaryio/drafter). 其他爱好者帮助发展一些 [工具](https://apiblueprint.org/tools.html) 与 API 蓝图合作,包括渲染器.

很久以来,我们公司一直使用Draver和 [阿廖](https://github.com/danielgtaylor/aglio) 渲染器为 用于处理亚太投资银行文件的标准。 但我们渐渐了解这些工具的功能 对我们来说还不够.

**蓝图** 因为它的源代码很难读取、维护和使用 技术已经过时。 项目作者放弃了,不接受新的更改请求. 我们还用自己的解析器代替了Drawer [曲折](https://github.com/funbox/crafter)。 。 。 .

我们的实现用JavaScript来写,它们很容易被前端开发者维护和发展.

## 特征

-   **现代设计.** 包括了黑暗主题!
-   **查找文档.** 您可以使用 URL 的一部分或标题来查找组,资源或动作,并快速访问它们.
-   **打印版本 .** 该版本删除了所有不必要的内容,并将强制内容放入了被修改的模式.
-   **选择者之一.** 我们的工具允许您选择不同的选项 [其中一个](https://apiblueprint.org/documentation/mson/specification.html#52-one-of-type) 元素和动态生成反应体.
-   **手动搜索页面.** 您可能发现搜索字段不足以找到描述的一部分 或特定属性。 手动搜索页面允许您使用标准浏览器查找器通过文本搜索.
-   **解析警告和错误的信息 .** 解析警告作为通知出现. 分析哪个块出错 页面渲染显示为有详细信息的单独页面.

## 安装

```shell
npm install --save @funboxteam/blueprinter
```

## 使用量

添加下一个命令 `package.json`数字 :

```json
{
  "scripts": {
    "dev": "blueprinter -i doc.apib -s -p 3000",
    "doc": "blueprinter -i doc.apib -o index.html"
  }
}
```

`dev` 脚本将在端口运行一个含有已渲染道克的活服务器并监视源文档的更改. `doc` 脚本将随文档生成 HTML 文件并保存为 `index.html`。 。 。 .

## CLI 选项

-   `-i, --input <file>` ——设置要渲染的源APIB文件.
-   `-o, --output <file>` ——设置输出 HTML 文件的名称.
-   `-s, --server` ——激活活服务器模式.
-   `-h, --host <host>` ——设置直播服务器主机. 默认值是 `127.0.0.1`。 。 。 .
-   `-p, --port <port>` ——设置活服务器端口. 默认值是 `3000`。 。 。 .
-   `--strict` ——允许解析“ 严格” 模式, 任何警告都会导致构建错误 .
-   `--css <file>` ——允许指定自定义 CSS 文件的路径. 文件的样式将附在页面上. 相关"蓝图"版本与自定义CSS文件之间可能存在的任何相容性问题,仍由文件开发者的良心来决定.
-   `--locale <locale>` ——设置用地语作为UI语言. 默认值是 `en`。可用的本地地址为 `en`, (中文(简体) ), `ru`。 。 。 .
-   `--favicon <file>` ——允许指定通往自定义favicon的路径. 仅适用于构建模式,而非dev模式. 只接受 PNG 文件 .

## 在 Docker 中运行

要以 Docker 容器的形式运行“ 蓝图” , 执行目录中的下一个命令, 并附带文档 :

```shell
docker run \
  --rm \
  -v $(pwd):/app \
  funbox/blueprinter -i doc.apib -o index.html
```

`--rm` 选项将在完成后自动清理并去除所创建的容器,以及 `-v` 选项将 将当前主机目录上载文档到容器中的某个目录.

图像默认工作目录设定为 `/app`因此,更容易上载 输入主机目录 `/app` 如上文的例子所示。 那样的话,只有名字 `you-doc-file.apib` 会没事的. 否则,您应该相对于容器路径中创建的APIB文件指定路径.

### Docker 和 Dev 服务器模式

要在 Docker 中运行 Blueprinter 作为 dev 服务器执行目录中的下一条命令并附带文档 :

```shell
docker run \
  --rm \
  -v $(pwd):/app \
  -p 3000:3000 \
  funbox/blueprinter -i doc.apib -s -p 3000
```

如果您指定 `-p` 蓝图的参数不同于 `3000`别忘了打开这个港口 从您的主机系统并修改 Docker 选项 `-p port:port`。 。 。 .

**请注意!** 当您通过 Dev 服务器进程停止时 `Ctrl/Cmd + C`,过程只是从终端分离 但容器本身仍然运行.

要停止容器使用下一个命令:

```shell
docker ps # get ID of the running container
docker stop <container> # stop container with specific ID
```

### 窗口中的嵌入容器

要运行 Windows 中的容器,请添加斜线(`/`) 之前 `pwd`数字 :

```shell
docker run \
  --rm \
  -v /$(pwd):/app \
  funbox/blueprinter -i doc.apib -o index.html
```

挂载目录可能为空 。 在这种情况下,请检查您的硬盘是否标记为共享 . 此设置可以在用于 Windows, 共享驱动器部分的 Docker 桌面的设置中找到. 如果磁盘没有共享,请标记为 `shared`,应用更改,并重新启动 Docker 桌面.

## 功能能力

### 迅速接触团体、资源和行动

HTML 页面带有已提供文档可搜索某些资源。 您可以将焦点设置为搜索字段 `/` 键.

对下列实体进行了搜索:

-   团体、资源和行动的标题和说明.
-   行动压力.

搜索结果出现在下个顺序 :

1.  匹配行动内容.
2.  团体名称、资源和行动的匹配.
3.  对群体、资源和行动的描述相匹配.

如果一个简单的搜索查询为 `empl` 联 合 国 `/list` 不够,您可以应用搜索修饰符(filters). 查询的一般形式是: `modType:modValue query` 地点 `query` 是想要的搜索查询。 您可以过滤结果 根据资源类型和HTTP方法.

-   按类型过滤 `type:action query`。可用值为 `type:group query`, (中文(简体) ), `type:resource query`, (中文(简体) ), `type:action query`。 。 。 .
-   通过方法过滤 `method:METHOD query` 地点 `METHOD` 是HTTP方法之一(GET,POST,DELETE等). 小写和大写都行.

因此,只列出带有以下内容的请求: `employ`,在搜索字段中键入:

```text
method:get employ
```

要应用修改器,查询应从 `modType`。这意味着,如果你需要找到文件中的短语 `method:get - filter example`,可以使用白空间作为查询的第一个符号( `method:get - filter example`) (中文(简体) ). 在此情况下,将不应用修改符,不考虑主白空间,并进行搜索 准确在句子上 `method:get - filter example`。 。 。 .

### 通过 `Ctrl/Cmd + F`

APIB文档可以包含很多不同的实体,因此搜索领域在某些情况下可能不会有所帮助 您需要找到属性值或URI参数。 为了手动找到一些东西,我们添加了单独的一页 文件所有内容的顺序列表。 要访问此页面, 请按图标按钮右到搜索字段 .

该页面包含所有分组、资源、请求和随后产生的回复。 属性中的所有属性 扩展各节。 因此,您可以通过浏览器搜索文档,例如使用 `Ctrl + F` 键组合.

### 另存为 PDF

文档的PDF版本被优化,以方便浏览. 文件开头的内容列表提供了简单 访问选定区域。 JSON计划的所有街区都藏了起来.

要将文档保存为 Chrome 浏览器中的 PDF, 请遵循下一步 :

-   通过搜索字段旁边的图标按钮来浏览手动搜索页面;
-   在浏览器上下文菜单中选择打印选项;
-   在打印对话框中选择“保存为PDF”和布局模式“肖像”;
-   保存带有选定设置的文档.

## 发展

### 依赖性安装

```shell
npm install
```

### 在 dev 模式下运行

```shell
npm start
```

默认dev服务器地址为http://localhost:8080.

### 构建

在当地运行项目

```shell
npm run build
```

### i18n 支持

该项目为UI文本提供多种语言支持(目前提供英语和俄语).

将文本标为已翻译, 使用 `t` 或者说 `Trans` 从 [@lingui/宏](https://lingui.js.org/ref/macro.html#overview)。 。 。 . 要使翻译在实际界面中出现,下一步应:

-   运行 `npm run extract` 更新 JSON 翻译目录(参见 `src/locales/{locale}/messages`(三);
-   为新案文填入缺失的译文;
-   运行 `npm run compile` 汇编翻译目录到 JavaScript 文件;
-   承诺所有改变.

## 为什么API蓝图

我们广泛使用JSON API 在公司, 所以每天我们的开发者 面对的问题 描述和批准API文件, 跟踪变化,在伙伴之间分发文件等。 这就是为什么我们觉得非常需要 方便的工具 与文件有关的工作.

从历史上看,这场战斗是在 [API 蓝图](https://apiblueprint.org/) 财务报告和审定财务报表 [斯瓦格语Name](https://swagger.io/)。 。 。 . 我们选择API蓝图有两个原因. 首先,使用API Blueprint描述的文献源代码对于人类来说更为可读. 第二,在进行研究时,Swagger缺乏几个重要特征,因为 `One Of` 支助.

## 贷项

这个项目的标志是很棒的 [伊戈尔·加里巴尔迪](https://pandabanda.com/)。 。 。 .

[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru/)

## 常见问题

### @funboxteam/blueprinter 是什么？

替换用于渲染的 Aglio 库生成的 AST 作为 HTML 页面 \.

### 如何安装 @funboxteam/blueprinter？

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

### @funboxteam/blueprinter 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/funboxteam\_\_blueprinter 是否存在。

### @funboxteam/blueprinter 可以商用吗？

@funboxteam/blueprinter 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @funboxteam/blueprinter 的下载量有多少？

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

### @funboxteam/blueprinter 还在维护吗？

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