Generate OpenAPI specification

[Michiel-s]

Problem

In many adminstrative IT-projects, the communication between services causes headaches because interfacing can quickly become complex. Ampersand helps with this problem because interfaces are checked statically. To be useful in practice, it is necessary to generate interface specifications that are usable directly in IT-projects. For this purpose, we want Ampersand to generate OpenAPI specifications.

Proposal

The Ampersand prototypes implement an API using the INTERFACE definitions as specified in the scripts. The frontend application (html/js) calls this API in order to get and manipulate data. In order to document the generated API and thereby make it reusable by other and for other applications (besides the generated frontend), we need to make the API explicit. A good way of specifying APIs is using the OpenAPI specification language (fka Swagger specification). The issue requests for composing a swagger file during prototype generation.

User story:

• After generating and deploying your Ampersand prototype, browse to http://pathtoyourapp/api/doc.
• Here you can view the API specification using the Swagger UI (http://swagger.io/swagger-ui/)

I've asked @jcnauta to work on this issue.

Position of swagger file in Ampersand prototype architecture:

Links: https://github.com/OAI/OpenAPI-Specification http://swagger.io/specification/