[HDFS-12690] Ozone: generate swagger descriptor for the Ozone REST Api

• Type: Sub-task
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Affects Version/s: HDFS-7240
• Fix Version/s: HDFS-7240
• Component/s: ozone
• Hadoop Flags: Reviewed
• Assignee: Marton Elek
• Reporter: Marton Elek
• Created: 20/Oct/17 09:49
• Updated: 26/Apr/18 21:55
• Resolved: 26/Oct/17 18:42

Description

This patch generates ozone.swagger.json descriptor during compilation time and adds it to the static/ web folder (available both from all web ui).

Note: I tested multiple method to generate swagger file: runtime and compilation time. Runtime needs more additional dependencies and multiple workaround as we have no ServletContext and ServletConfig in the netty based adapter (but it's possible to add a stub one). I prefer the compilation time generation because it more simplified and it also could be used to generate additional documentation.

This patch contains only the basic @Api/@ApiMethod annotations the parameters not yet annotated. Followup tasks:

• We can check how can we generate parameter level description from the javadoc. It is possible with custom docket + custom swagger reader, but maybe doesn't worth it.
• We can add a swagger ui (there are many implementations). It's a licence nightmare as most of the ui contains unlimited number of npm dependency with different (but mostly Apache + MIT) artifacts. I will suggest to add a swagger ui without the javascript and load it from cdn. It will work only with active internet connection but without licencing issue.
• Long term with this plugin we can also generate the content of OzoneRest.md (after a fine tuning the swagger annotations)