# @docspack/lapis 中文文档

规范地址：https://npmcn.com/package/%40docspack/lapis/

版本：0\.3\.0
npm 元数据更新时间：2026-10-03T06:02:38.894Z
中文译文更新时间：2026-11-12T14:05:36.240Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：219 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.5\.0
- 运行依赖：1 个
- 首次发布：2026-09-11T12:42:54.566Z
- 最新版本发布：2026-10-03T06:02:38.694Z
- 近 30 天下载量：24342（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

将 OpenAPI 3 文档转换为 LAPIS, 将 API 描述为语言模型的收缩标记 。 大约比JSON的同一份文件少了90%的代币.

## 安装

```sh
npm install @docspack/lapis
```

也可以使用：`pnpm add @docspack/lapis`、`yarn add @docspack/lapis`、`bun add @docspack/lapis`

## README

# @ docspack/ lapis (帮助)

**OpenAPI 3 输入, [利比里亚](https://github.com/cr0hn/LAPIS) 出来.** 大约90%的代币比同一种少 作为 JSON 文档.

LAPIS是描述 API 到 a _语言模式_ 而不是代码 生成器: 每项操作的签名, 紧凑类型, 以及 OpenAPI 的款次 线条倒塌成几个。 没有JavaScript的转换器,所以这是一个.

```bash
npx @docspack/lapis ./openapi.yaml
npx @docspack/lapis ./openapi.json -o api.lapis --stats
curl -s https://example.com/openapi.json | npx @docspack/lapis - > api.lapis
```

```
[meta]
api: Invoice Service
base: https://api.example.com/v2
auth: bearer header:Authorization

[types]
InvoiceCreate:
  customer_id: str
  due_date?: date

[ops]
create_invoice POST /invoices
  Creates an invoice for a customer.
  > body: InvoiceCreate
  < Invoice  # 201 The created invoice.
  @auth bearerAuth

[errors]
401 ApiError
  The token is missing, expired or invalid.
```

以所发表的文件——594项操作,1,454项计划,8.0 MB衡量:

```
594 operations, 1454 types, read as json
~193,593 tokens of LAPIS, against ~2,163,446 of JSON (91% smaller)
```

## 作为图书馆

```ts
import { parseOpenApi, toLapis } from "@docspack/lapis";

const document = parseOpenApi(await someOpenApiObject);
toLapis(document);
```

`parseOpenApi` 解决每个 `$ref`合并 `allOf`,并保持命名计划 **按名称** 这样 递归文档终止 。 它需要一个已解析的对象, 因此此切入点有 **没有 依赖关系** 并随地运行——包括浏览器.

读取一个文件或可能是YAML的文本是一个单独的切入点:

```ts
import { readApiFile, readApiText } from "@docspack/lapis/read";

const { document, format } = await readApiFile("./openapi.yaml"); // format: "json" | "yaml"
```

这种分化是包裹形状的点. `JSON.parse` 已建入每个 JavaScript 运行时间 以 0 字节计; YAML 需要解析器, 而解析器为 ~57 KB gziped 。 放下来 `/read` 表示浏览器捆绑 `parseOpenApi` 财务报告和审定财务报表 `toLapis` 没有船 `tests/entry.test.ts` 声称在已建产出上,而不是相信评论.

## 模型

两种渲染都来自一种形状—— `ApiDocument`,与 `operations`, (中文(简体) ), `types`, (中文(简体) ), `servers`, (中文(简体) ), `securitySchemes` 财务报告和审定财务报表 `tags`。它被导出,所以如果想要一个规范化的,它也可以单独使用 OpenAPI 文档而不是 LAPIS . `toGroups(document)` 用标签操作一个侧边栏.

## 三个界限,每个界限后面的测量

一个忠实的渲染器在真实文件上产生无法使用的产出. 每一个都存在,因为 与斯德莱克的规格相比

| 限制 | 没有它 |
| --- | --- |
| 类型关闭停留在象征性预算 | 每个条纹对象都有可扩展的字段指向另一个,因此一个操作到达了API的大部分: **66 500个纪念品** 一个终点 |
| 编号名单 8名成员 | 商船类矿井有297个,一次四次操作: **一行25 637个字符** |
| 内置对象扩展2个关卡, 12个字段 | 一个没有名称的文档使其整个身体树连成一线 |

一切都被计算在内 `+32 more`, (中文(简体) ), `{...}` 因为"这个形状还有更多"和"这个" 整个形状"是不同的主张,其中只有一个是真实的.

## 遵约

这里有一个东西不是LAPIS的语法: `@auth <scheme>` 在操作中行。 LAPIS 声明 认证在 `[meta]` 并且没有操作形式,所以文档中有些终点是 公众和其他人——大多数是公众——不能在符合要求的LAPIS中这样说。 释放出来 默认,因为这比符合性更值钱的模型是,然后关闭 `--strict` (或 `toLapis(document, { strict: true })`任何供养拒绝它的人的东西.

其他一切都是合法的LAPIS: `#` 注释带有成功状态,以及 `[errors]` 是该格式的 自己的一节——每份文件申报一次 `@ops:` 绑定一个不通用的错误.

## 它拒绝什么

每个都停止运行命令:

-   **斯瓦格2.0** —— 说 `npx swagger2openapi openapi.json -o openapi3.json`
-   **一个外部 `$ref`** —— 说 `npx @redocly/cli bundle openapi.yaml -o openapi.json`拒绝 而非抛出 : 静悄悄地取而代之的是“ 未知的 ” 的图案 没有尸体.
-   **A 类 `$ref` 点到无** - 命名,带指针.

## 谁用

这个软件包是Docspack的OpenAPI支持中共享的一半. `@docspack/openapi` 在此基础上—— 操作摘要、请求建楼、代码样本、尝试控制台——和 `docspack build --openapi` 将文档变成可搜索的文档包。 这些都用不着 此; 它将一种格式转换为另一种格式并停止 .

## 许可证

麻省理工学院. LAPIS 规格为 CC BY 4. 0并属于它的作者; 此套件执行一个 制造器.

## 常见问题

### @docspack/lapis 是什么？

将 OpenAPI 3 文档转换为 LAPIS, 将 API 描述为语言模型的收缩标记 。 大约比JSON的同一份文件少了90%的代币\.

### 如何安装 @docspack/lapis？

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

### @docspack/lapis 支持 TypeScript 吗？

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

### @docspack/lapis 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @docspack/lapis 需要什么版本的 Node\.js？

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

### @docspack/lapis 可以商用吗？

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

### @docspack/lapis 的下载量有多少？

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

### @docspack/lapis 还在维护吗？

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