[ogrim]

I would never write Swagger by hand; why should I when I can have it generated? We are using Swashbuckle[0] to generate Swagger for our ASP.NET Web API, which have been a great experience. We can explore and test the API in Swagger UI. I have been sprinkling a bit of hypermedia on top of this with HAL, mainly just for having links. I have never met anyone wanting to go the full HATEOAS route, but simple links can go a long wa. Swagger UI have been great for this, as HAL alone isn't really expressive enough to document what a link means. On the consumer side, I have been using NSwag[1] to generate clients with good results.

[0] https://github.com/domaindrivendev/Swashbuckle [1] https://github.com/NSwag/NSwag

[eddieroger]

> why should I when I can have it generated?

Because maybe you work on a team where half are creating an API and half are creating a client, and if you write a Swagger spec first, you can both be working at the same time, against the same contract, and just meet in the middle? And if you're working on the consumer side of things, you can take that spec and stand it up against a mocking engine that will now give you something to test against while your API team finishes their work? Just because you would rather generate Swagger doesn't mean there's not a reason to write it by hand before writing code.

[ogrim]

One can still do what you are describing and have the Swagger spec generated. On my platform, I would just specify data types and the interfaces, and have Swashbuckle parse this and spit out the Swagger spec. No need to hand-code Swagger while creating the contract up front. After this step, one could work at both sides of the contract independently as you describe.