APIs 您不会恨: API 样式指南
根据APIs You won't Hate, 使用这个浮出水面的命令行工具 打开API。 。 。 .
安装
npm install --save -D @apisyouwonthate/style-guide
npm install --save -D @stoplight/spectral-cli
使用量
创建本地规则来扩展样式指南 。 它最基本的形式只是告诉Spectral你想要使用什么规则,但它会允许你定制事物,加入你自己的规则,如果引起麻烦就关闭位.
cd ~/src/<your-api>
echo 'extends: ["@apisyouwonthate/style-guide"]' > .spectral.yaml
如果你使用VS代码或Stoplight Studio,那么国家防范机制模块将无法使用. 相反, 您可以使用 CDN 主机版本 :
echo 'extends: ["https://unpkg.com/@apisyouwonthate/[email protected]/dist/ruleset.js"]' > .spectral.yaml
说明: 您需要使用 CDN 主机规则的完整 URL, 因为 Spectral 无法通过扩展跟踪方向。 。 。 .
下一步, 使用 Spectral CLI 对您的 OpenAPI 描述进行插图 。 没有OpenAPI吗? 记录一些 HTTP 流量以制作 OpenAPI 然后可以切换到 API Design - First goings 前进.
spectral lint api/openapi.yaml
你应该看到一些输出像这样, 让你知道还有一些标准 你可以使用(呼出到 标准.REST:
/Users/phil/src/protect-earth-api/api/openapi.yaml
18:7 warning api-health Creating a `/health` endpoint is a simple solution for pull-based monitoring and manually checking the status of an API. paths
18:7 warning api-home Stop forcing all API consumers to visit documentation for basic interactions when the API could do that itself. paths
36:30 warning no-unknown-error-format Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc7807) or the JSON:API Error format. paths./v1/orders.post.responses[401].content.application/json
96:30 warning no-unknown-error-format Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc7807) or the JSON:API Error format. paths./v1/orders/{order}.get.responses[401].content.application/json
112:30 warning no-unknown-error-format Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc7807) or the JSON:API Error format. paths./v1/orders/{order}.get.responses[404].content.application/json
现在,你有一些事情 做你的API。 幸好这些只是警告 未连续整合 (除非 你想让他们) (中文(简体) ).
背面故事
你可以把你的API风格指南写成一个巨大的宣言 希望人们能看到它,或者你可以 自动化您的 API 样式指南 使用 Spectral 这样的工具,使您的 API 样式指南在拉请求级别上执行 。 这是任何成功的API治理方案的组成部分, 否则你们只是浪费时间 覆盖游戏中的基本内容太晚.
Spectral运行于OpenAPI和AsyncAPI上方,在编辑器中为林特提供动力,作为CLI工具,在连续集成等中并随其来 自己烤出来的 在 OpenAPI v2/v3 规则中. 就如何写出OpenAPI制定规则可以帮助初学者写出更好的OpenAPI,但其真正的力量是使用规则让实际的API更好,更一致,在涉及任何编程之前.
国家防范机制的这套资料汇集了在书籍和博客文章中发现的各种建议 APIS 你不会恨的 书 如果您将此应用到 API 生产中, 这基本上是 菲尔·斯通 免费判断您的 API 而不是 提供有偿咨询。但是,如果你能让这个 API Style 指南参与 API Design- First 工作流程中,你就可以免费获得关于如何在浪费任何时间编码之前设计更好的 API 的建议,这意味着在修复事物时减少倒向相容性中断 .
还有 一堆其他规则 您可以检查是否想要制作自己的 API 样式指南, 或者是否想通过拉动请求在此提供一些新规则 .
谢谢
- 安杰伊 伟大的规则为阿迪达斯风格指南做出了贡献.
- 瑙曼·阿里 - 创建
no-global-versioning作为他杰出的一部分 样式引导博客文章系列。 。 。 .
许可证
这个寄存器根据麻省理工学院的许可证获得许可.
提案国
如果你愿意感谢这位风格导师, 扔一些钱 保护地球在英国各地植树的慈善机构 保住了64英亩的古老林地菲尔把时间都花在这上面 都种了树 财务报告和审定财务报表 写API信不信!