Depends; if you're consumed and consuming in openapi it makes perfect sense. My own preference is building the schemas from annotations (aka. decorators) for a single source of truth.
I've found contract based a bit too verbose and disconnected to build fast with.
I've found the opposite - I can move much faster on services and clients that have OpenAPI docs than those with only markdown/undocumented APIs. With OpenAPI, I make the change in one place and everything else just regenerates and works. Without it, lots of slow manual testing and praying it works 🥲
My services usually involves fairly complex dependencies to other services so reusing oas typing from deps is often necessary for a meaningful end result w/o needless duplication.
With my annotated approach I meant that I am producing also openapi, but from the actual typing instead of matching my typing to a separate oas which would be compiled into types.
What is an oas ? So you write types in your main language, then generate openapi from them and maybe generate sdks from the generated openapi? that sounds good too
Pro - as it is all we have in terms of standardized HTTP API description. It does cover a lot but lacks means of describing higher order contractual concepts like session-scoped preconditions ("you need to do A before you can do B").
But as I said, it's much better than just prosa text.
Ah, and in an event-driven world, there is also OpenApi's message based sibling AsyncApi - that one I liked a lot because without it, event APIs never seemed to be treated as first class API citizens.
Comments
I've found contract based a bit too verbose and disconnected to build fast with.
But as I said, it's much better than just prosa text.
But I find pretty hard to find a place where it makes everybody happy enough, so people tend to diverse, and it makes less and less sense