作为最佳实践,我想将一些重要和关键的有用内容合并到我的API规范
- api相关常见问题解答
- 代码模板或食谱,以帮助消费者查看调用API的代码示例
- API订阅计划 服务水平目标
- 服务层协议
- 性能相关细节,如缓存。
我浏览了OAM 3.0的官方文档,似乎没有直接的标签来定义这些东西。
根据我的理解,这些是在管理api的其他一些地方定义的。在互联网上没有很多例子可以帮助满足这个要求。
我确实使用了Swaggerhub和Anypoint平台来创建使用3.0版本的开放API规范
我不认为OpenAPI规范有足够的表达能力来涵盖这一点,所以最好在一个单独的叙述文档中涵盖它们,您可以从您的规范中链接。
对于编写叙述性文档,文档管理开源工具包括像 这样的工具- Sphinx
- MkDocs
您可以在YAML文件的description
部分添加叙述链接。
请看这里的例子
YAML例子:
openapi: 3.0.2
info:
title: Open DeFi API
description: |
Long Markdown description goes here.
Add links here to your documentation here.