search

alexandrialibrary / Alexandria

Alexandria is a simple little card catalogue webapp with a terribly pretentious name.
MIT License
2 stars 1 forks source link

Consider moving all Swagger to Scala #62

Open hawkw opened 9 years ago

hawkw commented 9 years ago

Currently we're maintaining two separate versions of our Swagger API spec – the YAML version in doc/api/spec, and the embedded Scala DSL version in the actual API controller. Considering that our Swagger controller just serves the Swagger JSON file generated from the Scala DSL, it seems unnecessary to maintain two versions of our spec. It means that I have to rewrite the code in the Scala DSL when the API changes, and can lead to extra work and inconsistencies.

I think the only reason we used the YAML syntax was so that @redbassett didn't have to touch code with the .scala extension, but I don't think the syntax is that hard to figure out and one can probably write Swagger without having to learn the whole Scala programming language.

Therefore, would it be okay to just write the code directly in the controller and then add an autogenerated JSON/YAML file to the repo when the API changes?

redbassett commented 9 years ago

I like having the swagger for doc generation.

hawkw commented 9 years ago

The inline Scala DSL Swagger is useable for doc generation. The only differences are that we wouldn't have to maintain two separate versions of the spec, which I find leads to inconsistencies, and more of the docs would be generated directly from backend code, which also would reduce inconsistencies and mistakes.

redbassett commented 9 years ago

https://xkcd.com/1481/