Implement automatic generation of Open API / Swagger documentation from JavaDoc comments in controllers

[ipolevoy]

the idea is to develop the OpenAPI documentation directly in the controller Java files as JavaDoc, but then generate the OpenAPI - compatible format to expose as real documentation. This way, the JavaDoc will also serve and an official API documentation.

Also, it makes sense to carve out blocks of JavaDoc for this, such that if any content is outside such a block, it will not be part of the exposed API - this is necessary for internal comments, implementational detail, etc.

[ipolevoy]

Interesting resources:

https://developer.ibm.com/technologies/api/blogs/document-apis-with-open-source-openapi-comment-parser/

[ipolevoy]

this is somewhat related: https://github.com/OpenAPITools/openapi-generator - generates server stubs based on OpenAPI spec.

However, the first support is to generate API docs from comments in code

[ipolevoy]

also, see this: javaparser/javaparser#325

[ipolevoy]

Here is another good resource: https://github.com/readmeio/swagger-inline

[ipolevoy]

It makes sense to make it possible to:

1. generate json definitions at build time
2. Generate definitions at run time using a special controller

[ipolevoy]

For the option 2, need to compile with javadoc though

[ipolevoy]

Maybe generate defs at run time and serve that live?

[ipolevoy]

Once this is implemented, comment here: https://stackoverflow.com/questions/55805156/swagger-support-for-javalite-project