3 ms·
Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagge
by emidln 10y ago
Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]).
[0] https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api
[1] https://github.com/metosin/ring-swagger https://github.com/metosin/ring-swagger
- paulddraper 10y agoI didn't realize Swagger was meant to be an intermediate format.
- emidln 10y agoIt's not an intermediate format necessarily, but it reflects information already encoded in your route definitions. It seems silly to maintain that information twice in two different locations.
- darrelmiller 10y agoHence the reason for tools like swagger-inflector http://swagger.io/writing-apis-with-the-swagger-inflector/ http://swagger.io/writing-apis-with-the-swagger-inflector/ that allows you to drive routing directly from the OpenAPI definition
- gkoberger 10y agoIn my experience (we have a product where people upload Swagger files), most people write it by hand. There's two reasons: 1) Many people use Swagger to design (rather than document), meaning the Swagger comes before the code 2) Most people just prefer to write it out, since the tooling otherwise isn't necessarily great (especially for non-developers) We ran a poll and "by hand" (either on Swagger Hub/Apiary, or locally) won by a landslide.
- dwaltrip 10y agoHow does a non-developer know how to document or design an API?
- numbsafari 10y agoPerhaps the first pass of the doc is written by a developer but it is later updated by a tech-writer, or you need to produce a translated version.
- eddieroger 10y agoI do and have, yes. We generally push for design-first specs, which means there's nothing in place to generate the Swagger file yet. If the API is simple, as they should be, then it's not that awful, really.