feat(swagger): use swagger-ui-express to display simple and administration api doc

[jmkerloch]

• add api documentation in docker image
• convert api documentation in yaml to json
• serve swagger-ui with swagger-ui-express

Simple and administration openapi are available.

related #84

[azarz]

I personally think that's a great way to display the API documentation.
I will wait for @lgrd 's return to approve the PR.

[lgrd]

Hi,
Thank you for this idea. I think it is a good way to complete the getcapabilities.

May I suggest you a few more steps for this feature ?

• convert the YAMLs to JSONs, so it will avoid one dependency.
• read the new JSONs during the init step of the each API (we can talk about this if you want ;) )
• serve those new pages on /{api}/1.0.0/openapi.
• create the page for the admin API too, so the project will be completely available for humans.
• update the changelog

[jmkerloch]

convert the YAMLs to JSONs, so it will avoid one dependency.

You mean replacing api.yaml to api.json ?

read the new JSONs during the init step of the each API

If the API is described with JSON file we can just use this file directly for swagger-ui-express:

var swaggerDocument = require('./api.json');
router.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

[lgrd]

@jmkerloch Yes, I think we could replace it. I've seen it could be a JSON => https://spec.openapis.org/oas/latest.html#format

For the init step, you have a init file where you can do what you need to prepare your data.

[lgrd]

that's ok for me :)