@funboxteam/蓝印机
蓝图 是一个 API 蓝图 变形器。 它使用API AST的形式为: API 元素 并生成带有文档的 HTML 页面.
{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得呢
理由
API 蓝图标准主要由 阿皮亚里,它拥有官方解析器 起草者. 其他爱好者帮助发展一些 工具 与 API 蓝图合作,包括渲染器.
很久以来,我们公司一直使用Draver和 阿廖 渲染器为 用于处理亚太投资银行文件的标准。 但我们渐渐了解这些工具的功能 对我们来说还不够.
蓝图 因为它的源代码很难读取、维护和使用 技术已经过时。 项目作者放弃了,不接受新的更改请求. 我们还用自己的解析器代替了Drawer 曲折。 。 。 .
我们的实现用JavaScript来写,它们很容易被前端开发者维护和发展.
特征
- 现代设计. 包括了黑暗主题!
- 查找文档. 您可以使用 URL 的一部分或标题来查找组,资源或动作,并快速访问它们.
- 打印版本 . 该版本删除了所有不必要的内容,并将强制内容放入了被修改的模式.
- 选择者之一. 我们的工具允许您选择不同的选项 其中一个 元素和动态生成反应体.
- 手动搜索页面. 您可能发现搜索字段不足以找到描述的一部分 或特定属性。 手动搜索页面允许您使用标准浏览器查找器通过文本搜索.
- 解析警告和错误的信息 . 解析警告作为通知出现. 分析哪个块出错 页面渲染显示为有详细信息的单独页面.
安装
npm install --save @funboxteam/blueprinter
使用量
添加下一个命令 package.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 容器的形式运行“ 蓝图” , 执行目录中的下一个命令, 并附带文档 :
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 服务器执行目录中的下一条命令并附带文档 :
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,过程只是从终端分离
但容器本身仍然运行.
要停止容器使用下一个命令:
docker ps # get ID of the running container
docker stop <container> # stop container with specific ID
窗口中的嵌入容器
要运行 Windows 中的容器,请添加斜线(/) 之前 pwd数字 :
docker run \
--rm \
-v /$(pwd):/app \
funbox/blueprinter -i doc.apib -o index.html
挂载目录可能为空 。 在这种情况下,请检查您的硬盘是否标记为共享 .
此设置可以在用于 Windows, 共享驱动器部分的 Docker 桌面的设置中找到.
如果磁盘没有共享,请标记为 shared,应用更改,并重新启动 Docker 桌面.
功能能力
迅速接触团体、资源和行动
HTML 页面带有已提供文档可搜索某些资源。 您可以将焦点设置为搜索字段 / 键.
对下列实体进行了搜索:
- 团体、资源和行动的标题和说明.
- 行动压力.
搜索结果出现在下个顺序 :
- 匹配行动内容.
- 团体名称、资源和行动的匹配.
- 对群体、资源和行动的描述相匹配.
如果一个简单的搜索查询为 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,在搜索字段中键入:
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”和布局模式“肖像”;
- 保存带有选定设置的文档.
发展
依赖性安装
npm install
在 dev 模式下运行
npm start
默认dev服务器地址为http://localhost:8080.
构建
在当地运行项目
npm run build
i18n 支持
该项目为UI文本提供多种语言支持(目前提供英语和俄语).
将文本标为已翻译, 使用 t 或者说 Trans 从 @lingui/宏。 。 。 .
要使翻译在实际界面中出现,下一步应:
- 运行
npm run extract更新 JSON 翻译目录(参见src/locales/{locale}/messages(三); - 为新案文填入缺失的译文;
- 运行
npm run compile汇编翻译目录到 JavaScript 文件; - 承诺所有改变.
为什么API蓝图
我们广泛使用JSON API 在公司, 所以每天我们的开发者 面对的问题 描述和批准API文件, 跟踪变化,在伙伴之间分发文件等。 这就是为什么我们觉得非常需要 方便的工具 与文件有关的工作.
从历史上看,这场战斗是在 API 蓝图 财务报告和审定财务报表 斯瓦格语Name。 。 。 .
我们选择API蓝图有两个原因. 首先,使用API Blueprint描述的文献源代码对于人类来说更为可读.
第二,在进行研究时,Swagger缺乏几个重要特征,因为 One Of 支助.
贷项
这个项目的标志是很棒的 伊戈尔·加里巴尔迪。 。 。 .
