API Documentation about play-scala-template.g8 HOT 2 CLOSED

There is a high level discussion to be had here, regarding engineering and good practice. Here's my point of view :

Swagger/OpenAPI is an IDL (interface description language), and can serve as a blueprint for an API. In my point of view, this is much more valuable than just a way to document an implementation (which happens if you use the default swagger plugin that requires you to annotate your json models and methods in your implementation).

When you build anything, the specification should come first, and Swagger/OpenAPI is a way to formalise the specification. It is a language that allows everyone, both producers and consumers, to describe what the API is going to be served and how it is going to be consumed, without any misunderstanding. The metamodel is pretty well described and does not allow any misunderstanding.

The way we are working on our current project is, every time we get a story, to first translate and formalise the requirements into a swagger specification. Then, once the specification is agreed upon, actually change the implementation. In other words, we formally agree on the interface before starting any implementation. Using the yaml format instead of json, the specification is humanly readable and understandable.

There is also a lot of tooling around swagger. We're currently exploring a node-js tool that generates the backbone for functional tests from a swagger specification. Swagger-ui was added to the project in a frictionless way without having to pollute the implementation with annotations.

The only issue is that this workflow (that in my opinion makes for better engineering) does not benefit from a Play integration. The ideal for me would be to have some generators that would take a Swagger specification and generate models, json formats and a router, and I think that's something the company should put effort into, and leave aside the routes file. Play routes file is very imperfect, it describes a very small part of what an API is, and it is left to the implementation to decide things such as the accept / content-types, parameters and result models, status codes involved. Its existence is only justified by the need to provide a reverse-routing mechanism for twirl templates (which are not used when writing microservices anyway). It creates a useless layer of complexity, and the generated code fails to pass the compilation through some flags, in some cases.

Misc notes :

• Note that [RAML][http://raml.org/) is a good alternative to swagger when it comes to IDL to HTTP/REST APIs
• gRPC is superb in the IDL regard. I wish we were using it, as it really makes it easier to write APIs. It comes with a gateway to expose the API to traditional HTTPv1 clients, and both clients and server stubs can be generated for ScalaJVM using ScalaPB

from play-scala-template.g8.

Referenced in #20

from play-scala-template.g8.