@ docspack/ lapis (帮助)
OpenAPI 3 输入, 利比里亚 出来. 大约90%的代币比同一种少 作为 JSON 文档.
LAPIS是描述 API 到 a 语言模式 而不是代码 生成器: 每项操作的签名, 紧凑类型, 以及 OpenAPI 的款次 线条倒塌成几个。 没有JavaScript的转换器,所以这是一个.
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)
作为图书馆
import { parseOpenApi, toLapis } from "@docspack/lapis";
const document = parseOpenApi(await someOpenApiObject);
toLapis(document);
parseOpenApi 解决每个 $ref合并 allOf,并保持命名计划 按名称 这样
递归文档终止 。 它需要一个已解析的对象, 因此此切入点有 没有
依赖关系 并随地运行——包括浏览器.
读取一个文件或可能是YAML的文本是一个单独的切入点:
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并属于它的作者; 此套件执行一个 制造器.