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
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-maturityenum : 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.–.
