Add OpenAPI 3.0.x compatibility documentation.

[mbarnach]

Make the middlewares documentation aware
Add optional getters to the middleware to document better your code.
Keep 100% compatibility with Swagger 2.0 documentation.

Description

Generate an OpenAPI 3.0.x documentation using the Kitura-OpenAPI framework.
The new features are:

• a better documentation of the routes;
• middlewares can now add extra documentation about their parameters and their security policy;
• sub-router are fully supported: sub-router routes are visible in the documentation;
• security schemes can be documented
• tags are supported;
• servers can be fully described.

This PR requires Kitura-OpenAPI PR #29 (Kitura/Kitura-OpenAPI#29) for a correct display of OpenAPI specification. This is not affecting the Swagger 2.0 display.

Motivation and Context

The automatic documentation of routes could be improved.
The OpenAPI 2.0 (aka Swagger 2.0) is outdated and the 3.0 should be used instead.

How Has This Been Tested?

A side project to see the result is available in https://github.com/mbarnach/KituraOpenAPIExample

Checklist:

• If applicable, I have updated the documentation accordingly.
• [/] If applicable, I have added tests to cover my changes.

[djones6]

Thank you! This is a great piece of work.

The only comment I have is that it would be good to have test coverage for the new generator. But we could raise an issue for that, and it might make a good first issue for someone looking to contribute.

[mbarnach]

I will write the tests now. I think it makes sense to have both in-place, as it is too easy to break something. By the way, in the PR, I've fixed the usage of array in Swagger 2.0 that was broken with some getter with middlewares. It will be big to cover everything, but I will try to setup the groundwork for it.

[CLAassistant]

All committers have signed the CLA.