Open API Spec

Swagger or OpenAPISpecification is the way to specs or documentation for Restful web services.

You can write the spec first, and then generate interfaces and models from it or you can generate the spec from your code. Both ways are fine.

I think all web services should use Open API Sepcs. Becase you can auto generate client code and all kinds of cool stuff.

Let's say you write an API, and then you're going to write a web app, an iOS app and maybe some android thing later.

With an OpenAPI spec you could autogenerate the clients for all of them, and move on to focusing on making the apps instead of writing HttpClient code.