Just to drop another two cents in here - I feel like code-first is great when it's a solo project or very experimental, but when you're working on a larger team, or more to the point, working with other teams, spec-first is invaluable.
You can publish a working spec long before worrying about any sort of technical implementation, which means you can get feedback from the other teams involved, which can save an immense amount of time. Additionally, the other team can start working from your clear spec sooner, so you unblock them, AND there are all kinds of great mocking tools to fake your api until it's actually done. Oh, and there are libraries that can check your requests/responses in your tests, to ensure you're keeping to the agreed-on spec, so it makes tests more valuable and easier to write, too!
Honestly, even with all that, I wasn't sold on spec first at first because authoring OpenAPI specs SUCKS. It's such a verbose and hard to read and write format. But then I found TypeSpec, and I haven't looked back. I'm converted our existing specs to TypeSpec and they're half the size or less (usually way less). This is easier to write, but critically, easier to read, which makes PRs against a spec a lot more understandable and meaningful.
If you've ever been on the fence about spec-driven development, give TypeSpec a try. It was a real game changer for me.
Cool, I introduced something like typespec at the last company i worked for and it was great. We called it the domain graph and we able to generate entire platform APIs and clients.
I still want to build something that can handle protocol evolution and also do protocol up/down migration on the response (like the stripe API team has done).
You can publish a working spec long before worrying about any sort of technical implementation, which means you can get feedback from the other teams involved, which can save an immense amount of time. Additionally, the other team can start working from your clear spec sooner, so you unblock them, AND there are all kinds of great mocking tools to fake your api until it's actually done. Oh, and there are libraries that can check your requests/responses in your tests, to ensure you're keeping to the agreed-on spec, so it makes tests more valuable and easier to write, too!
Honestly, even with all that, I wasn't sold on spec first at first because authoring OpenAPI specs SUCKS. It's such a verbose and hard to read and write format. But then I found TypeSpec, and I haven't looked back. I'm converted our existing specs to TypeSpec and they're half the size or less (usually way less). This is easier to write, but critically, easier to read, which makes PRs against a spec a lot more understandable and meaningful.
If you've ever been on the fence about spec-driven development, give TypeSpec a try. It was a real game changer for me.
https://typespec.io/