News for hackers. Stuff that matters.
Re:Problems with Swagger by emidln on Tuesday April 04, 2017 @04:20PM (#14036797)
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

[1] https://github.com/metosin/ring-swagger

Re:Problems with Swagger by gkoberger on Tuesday April 04, 2017 @05:10PM (#14037238)
In 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.

Re:Problems with Swagger by dwaltrip on Tuesday April 04, 2017 @10:55PM (#14039298)
How does a non-developer know how to document or design an API?
Re:Problems with Swagger by numbsafari on Tuesday April 04, 2017 @11:31PM (#14039459)
Perhaps 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.
Re:Problems with Swagger by eddieroger on Wednesday April 05, 2017 @08:24AM (#14041545)
I 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.
Re:Problems with Swagger by paulddraper on Tuesday April 04, 2017 @04:45PM (#14037029)
I didn't realize Swagger was meant to be an intermediate format.
Re:Problems with Swagger by emidln on Tuesday April 04, 2017 @04:49PM (#14037059)
It'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.
Re:Problems with Swagger by darrelmiller on Wednesday April 05, 2017 @01:07AM (#14039816)
Hence the reason for tools like swagger-inflector http://swagger.io/writing-apis-with-the-swagger-inflector/ that allows you to drive routing directly from the OpenAPI definition