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

Question

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

注意:现在，我们构建了许多API，它们正处于不同的开发阶段。是否有方法对此进行注释，以便其他开发人员知道仍在进行中的API

Answer 1

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

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

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

x-maturity枚举: API的成熟度。要使用的值：development、staging、production。

另一种方法是在API版本中表示您的API成熟度/就绪状态。语义版本化允许您在版本中为预发布附加附加标签。例如，任何开发人员都应该知道1.0.0-alpha.1或1.0.0-dev.1版本的API仍在进行中，还没有准备好使用。

预发布版本可以通过紧接补丁版本之后附加连字符和一系列点分隔标识符来表示。.预发布版本表示该版本是不稳定的，可能不满足其关联的正常版本所表示的预期兼容性要求。例子: 1.0.0-alpha，1.0.0-α1，1.0.0-0.3.7，1.0.0-x.7.z.92，1.0.0-x-y-z-。