Github user merrimanr commented on the issue:
https://github.com/apache/incubator-metron/pull/535
The REST API is documented with annotations. This is standard practice and
powers the in context documentation in the Swagger UI. It was requested that
this documentation also be included in the README so README.vm (a velocity
template) is provided to generate the API README content from the annotations.
The catch is that you have to keep the READMEs in sync outside of the API
section. Or, without it, you would have to keep the README in sync with the
annotations. In practice I'm not sure which one is more worse, it's annoying
either way. My personal preference would be to reference Swagger for REST
documentation (and not duplicate it) but I understand why we included it.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
