@ docspack/ openapi

Docspack 用 OpenAPI 文档做什么 .

读取文档并将其作为LAPIS @docspack/lapis,可发布 因为它的转换对永远也碰不到文件包的人有用。 这个软件包是 上面的所有东西——它都再出口模型,所以你需要一个进口而不是两个:

• 代理人 - 密集的操作 摘要: 基准 URL、证书、输入 它们的种类,身体形状,反应,失败和可运行 curl 打电话,在 利比里亚 标记;
• 一个人 —— CURL, JavaScript, Python 和 Go 中的请求构建器和代码样本, 加上 尝试控制台的行为.

两者都来自同一个解析器和同一个请求构建器,所以一个页面上的样本,请求 控制台发送一个代理被回答的示例不能有异议 .

它唯一的依赖是 @docspack/lapis,主要条目没有它自己的, 所以这个运行在 CLI和浏览器都一样.

import { parseOpenApi, operationDigest, codeSamples, toGroups } from "@docspack/openapi";

// `parseOpenApi` and `toGroups` come from @docspack/lapis, re-exported here.
const document = parseOpenApi(JSON.parse(await readFile("openapi.json", "utf8")));
const [operation] = document.operations;

operationDigest(document, operation); // the dense text an agent gets
codeSamples(document, operation); // cURL, JavaScript, Python, Go
toGroups(document); // operations grouped by tag, for a sidebar

为什么是摘要而不是文件

在 API 中,一个代理发送的 OpenAPI 文档被传送到每个操作,以回答关于 一个 根据斯德莱克公布的规格——594项操作,1,454项计划,8.0 MB of JSON:

反对: 最小的正确切片 openAPI JSON 用于单一操作——操作 它的参考计划,安全计划 和它的服务器, 一份摘要 大约72% (单位:千美元)tests/digest.test.ts 持有该号码到一楼).

有三个限制是可能的,每个限制都存在,因为没有限制是衡量的:

• 命名类型由名称所携带. 从一个 " 花纹 " 行动到完全过渡性关闭 大多数API, 因为每个对象都有可扩展的字段指向另一个: 文摘来了 每人66500个 步行是从行动本身的图谋中走出第一线,然后停站 一个象征性的预算, 命名哪些是不适合的.
• 内置对象扩展出两个关并列出十二个字段. 无报酬的文档 在这里.
• 点名会列出8名会员. 斯德莱克的商家类别 enum有297个 而且出现4个 时值在一个操作中——一行有25 637个字符.

任何滑动都算在内(+32 more, (中文(简体) ), # not expanded here: …)),因为"还有更多的这个 形状"和"这是整个形状"是不同的主张.

LAPIS, 与它不同的摘要

利比里亚 (v0.1.0, CC BY 4. 0)是描述API的开放式格式 到语言模型。 它被通过而不是取而代之的是我们自己的标记:一种模式 已经看到它没有被教育就被剖析了 储蓄是结构性的 这个 渲染器及其一个有文件记录的扩展在 @docspack/lapis。 。 。 .

另有两个偏差属于 摘要 特别是,因为它描述了一个操作 而不是整个API:

1. 错误按摘要列出,作为 <status> <Type> # <description>,而不是在一个 全文件 [errors] 区域 @ops: 装订. toLapis 整个文件渲染.. 这是LAPIS最大的单一储蓄来源.
2. 成功状态将随着 # 注释 编辑 < 线条。 LAPIS 输出标记携带 一个类型,没有别的,和 201 对 204 改变打电话者下一步会做什么.

尝试控制台

@docspack/openapi/console 是一个 DOM 模块,而不是组件 :

import { mountApiConsoles } from "@docspack/openapi/console";

mountApiConsoles(); // claims every [data-api-console] on the page

标记使静态——一种贴有标签的填充形式,确切显示终点是什么—— 这使得发送按钮有效. 证书从不存储: 从字段读取 发送时间 并保存在任何 超过请求。 没有 localStorage,没有 sessionStorage,没有 饼干.

@docspack/sheaf-react 使标记本模块理解 .

许可证

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