[whizzter]

We use OpenAPI/Swagger specs whenever possible for new projects and integrations (some usages or integrations are older).

Generating a OpenAPI/Swagger spec in .NET is as easy as telling a lib like NSwag to generate and publish documents from your API's (and you can filter out to only show public API's in the docs). Probably as easy in Java,go,etc.

Consuming services can usually be done almost as easily by downloading the spec and pointing a code-generator to it.

HOWEVER the mandatory vs opt-in part is why we are stuck with JSON based api's, consuming/providing the typings becomes extra work when interfacing/playing with an API from any dynamic language such as JS, Python, Ruby, etc whilst you really only pay a relatively minor performance penalty from typed languages that people won't care about in dev up until it hits in production (Assuming you have an modern JSON serializer library built for speed).

Anything resembling "bloat"/complexity (sadly types is in this category from the perspective of many anti-TS JS developers, esp as API-typings still won't come from the host language but having to be provided separately) will be offputting and lead to any such spec being ignored by a substantial chunk of developers.