英语 | русский
@diplodoc/openapi-extension (英语)
Diplodoc平台的OpenAPI扩展. 规定:
- Markdown 它的变换插件
openapi-sandbox栅栏地块. - 一个将 OpenAPI specs 转换成 Markdown 页面的包含器 .
- 一个浏览器运行时间(React UI)来渲染交互式OpenAPI sandbox.
特征
- YFM 语法支持
- 外观渲染数字 :
oneOf编号 :allOf, enums, 循环引用 - 沙盒用户界面: 交互请求/响应 UI 在浏览器中提供
- 包含管道: 从 OpenAPI 定义生成 Markdown 文件
安装
npm install @diplodoc/openapi-extension
使用量
变形插件( E)openapi-sandbox 块)
向变压器添加插件 :
import transform from '@diplodoc/transform';
import {transform as openapiSandbox} from '@diplodoc/openapi-extension';
const markdown = `
\`\`\`openapi-sandbox
method: post
path: /test
server: http://localhost:8080
\`\`\`
`;
const {result} = await transform(markdown, {
plugins: [openapiSandbox()],
});
插件转换 openapi-sandbox 栅栏可以进入 DOM 节点,运行时间可以在浏览器中水合.
包含器( OpenAPI ~ Markdown)
包含器切入点导出为 @diplodoc/openapi-extension/includer用于建造管道:
- 校验 OpenAPI 规格
- 确定和规范引用
- 生成端点和图案部分的 Markdown 页面
这个 sandbox 选项接受 host 财务报告和审定财务报表 customHost中的 YFM 预设变量 host 为:
在生成页面时解决。 设定 customHost: true 以显示主机输入
沙盒;其上报的数值由每个项目,规格修改和操作存储.
提交空值还原配置 host。 。 。 .
sandbox:
host: "{{apiHost}}"
customHost: true
条件中的预设变量
这个 noindex, (中文(简体) ), filter,以及 hidden 选项中接受液体表达式
endpoint 财务报告和审定财务报表 tag 字段。 端点或标签属性可直接使用;
预设变量在 vars。不要将这些表达式围起来 {{ }}。 。 。 .
# presets.yaml
default:
noIndexOperations: [deletePet]
# toc.yaml
items:
- name: API
include:
path: api
mode: link
includers:
- name: openapi
input: petstore.yaml
noindex:
endpoint: vars.noIndexOperations contains operationId
生成 deletePet 端点页面为 noIndex: true 在其前题;
其他端点页仍可索引。 该页面仍在生成并包含在TOC中.
标记条件可以使用 tag: vars.noIndexTags contains name 换句话说.
匹配标记也收到 noIndex: true 在他们生成的登陆页面.
仅端点条件不会改变其标记的登陆页面索引.
为包含这些内容的技选委员会使用其目录和
祖先 presets.yaml 文件,而不是规格或生成的输出目录.
--vars-preset 选择覆盖的预设 default 在每个文件中; 更接近
预设文件优先于祖先文件. --vars 覆盖预设值.
阵列、布林克数、数字和嵌入对象都得到支持.
一个空的 noIndexOperations 数组匹配无终点.
程序呼叫员 includer(run, params, tocPath) 必须初始化它们的变量
在援引加入者之前先提供服务。 CLI在处理TOCs之前这样做.
关于处理阶段的详细情况,见:
adr/ADR-002-openapi-processing-pipeline.md
运行时间( 浏览器 UI)
运行时间导出为 @diplodoc/openapi-extension/runtime。它使交互式用户界面变为 .yfm-openapi-sandbox-js 变换插件产生的占位符.
在您的捆绑中导入运行时间条目和样式 :
import '@diplodoc/openapi-extension/runtime';
import '@diplodoc/openapi-extension/runtime/styles';
发展
npm install
npm run typecheck
npm test
npm run lint
npm run build
文档
- 发展成果评估 :
adr/ - 代理笔记 :
AGENTS.md
许可证
见 LICENSE。 。 。 .