Hacker News Reader

Comment by emidln | Hacker News Reader

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

View on HN

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.

How does a non-developer know how to document or design an API?

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.

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.

I didn't realize Swagger was meant to be an intermediate format.

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.

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

Reply on news.ycombinator.com