How to mark APIs as unused in OpenAPI 3.x

Question

How to mark APIs as unused in OpenAPI 3.x, when the library is not ready for consumption by other microservices which intend to use the API

Note: Right now, we build a lot of API(s) and they are in various stages of development. Is there a way to annotate this, so that other developers know that there are API(s) which are still work in progress

Answer 1

OpenAPI specification till 3.1.0 doesn't define a way to describe the maturity level of the API.

There was a proposal about adding /info/lifecycle to describe lifecycle and maturity information. But it doesn't seem to get conclusion.

You can define OpenAPI extension to store the information. Just like the /info/x-maturity in Smart API Specification:

x-maturity enum : Maturity of the API. Values to use: development, staging, production.

Another way is to represent your API maturity/readiness in the API version. The semantic versioning allows you to append additional labels for pre-release in the version. For example, any developer should know an API with version 1.0.0-alpha.1 or 1.0.0-dev.1 is still work in progress and not ready for use.

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. ...... A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.