如何在 OpenAPI 3.x 中将 API 标记为未使用

Question

当库尚未准备好供打算使用 API 的其他微服务使用时，如何在 OpenAPI 3.x 中将 API 标记为未使用

注意：目前，我们构建了很多 API，它们处于不同的开发阶段。有没有办法对此进行注释，以便其他开发人员知道有一些 API 仍在进行中

Answer 1

OpenAPI 规范直到 3.1.0 都没有定义描述 API 成熟度级别的方法。

\n

有一项关于添加描述生命周期和成熟度信息的提案/info/lifecycle。但似乎还没有得出结论。

\n

您可以定义 OpenAPI扩展来存储信息。就像智能 API 规范/info/x-maturity中一样：

\n

\n

x-maturity enum ：API 的成熟度。使用的值：development、staging、production。

\n

\n

另一种方法是在 API 版本中表示您的 API 成熟度/准备情况。语义版本控制允许您在版本中附加预发布的附加标签。例如，任何开发人员都应该知道 API 的版本1.0.0-alpha.1或1.0.0-dev.1仍在进行中且尚未准备好使用。

\n

\n

预发布版本可以通过在补丁版本后面附加连字符和一系列点分隔的标识符来表示。...... 预发布版本表示该版本不稳定，可能无法满足其关联的正常版本所表示的预期兼容性要求。示例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、\n1.0.0-x.7.z.92、1.0.0-xyz.\xe2\x80\x93。

\n

\n