Swagger: The World's Most Popular API Framework
swagger.io
swagger.io
In a lot of cases I see Swagger.json files being generated by reflecting over the actual code, but I seldom hear from people manually writing specifications.
I believe this can be very interesting since it allows you to centralize documentation, generate protocol-agnostic clients to share with other teams in your organisation, etc.
RAML seems to have more support for extensibility (i.e. annotating API endpoints with custom parameters that are not in the official spec) though. Not sure if OpenAPI 3.0 has more support for that, too.
Writing the schema is always a painful experience. I find the result overly verbose and not human friendly. Which makes me think that these things shouldn't be hand crafted.
> I believe this can be very interesting since it allows you to centralize documentation, generate protocol-agnostic clients to share with other teams in your organisation, etc.
On the paper yes, but I have yet to come across formal API specification used this way. The only usage I see in the wild is the generation of web API browsers, a la swagger UI.
How can I self host the API documentation (as reference) without setting up the whole UI? Everything I've tried is "experimental", "not tested" and "almost working".