Documentation: Add swagger.io provider to microservices to document our web services

[whikloj]

Using swagger.io allows us to build API documentation with code annotations. Swagger is part of OpenAPI which continues our adoption of good standards.

For Silex we can use the silex-swagger-provider to automatically publish API documentation.

[ruebot]

See also #120

[whikloj]

Based on the fact that the silex-swagger-provider is not supporting Swagger 2 I think we should look at implementing zircote/swagger-php instead.

[ruebot]

@whikloj should we be concerned with any of the rationale provided there why the silex-swagger-provider is not supporting Swagger 2?

[whikloj]

I'm not sure I fully understood his rationale at first so I played with his code and was able to get it working with Swagger 2. However this lead to a larger problem which is that at present OpenAPI/Swagger does not support content-negotiation for parameter definition.

What this means is that we can't define that a POST to /islandora/resource should expect a body of RDF if the mime-type is text/xml or application/rdf+xml or application/ld+json, but _ALSO_ expect a body of a binary if the mime-type is image/tiff or video/mp4.

Soooooooooo... going back I read the articles and had a look at the JSON Schema documentation. Its interesting just not sure if we have the time to generate all the JSON schemas?

[ruebot]

...inteeeeeeeeeeeeeeeeeeeeeeeeresting.

[whikloj]

Yes, so that ticket with OpenAPI seems to indicate that this should be coming in the next version. Question is when will that be?

[whikloj]

However....doesn't it look nice?!