action #16282
Updated by okurz about 7 years ago
## User story
As an openQA API user I want documentation of available API commands in easier to read format so that I am motivated to use the API more often
## acceptance criteria
* **AC1:** the API documentation provides grouping based on use cases
* **AC2:** documentation provides something human readable
* **AC3:** documentation is automatically updated from source code
## tasks
* Evaluate https://metacpan.org/pod/Mojolicious::Plugin::Swagger2
* if feasible rewrite current WebAPI.pm to use that
* alternatively add POD markup for the routes and extract that as part of documentation generation
## further details
Currently we have all available API routes listed on all unknown routes, e.g. https://openqa.opensuse.org/all_the_routes but they are missing some human description and are also not grouped in a sensible way by use, only by definition.
Other interesting references:
* http://petstore.swagger.io/#!/pet/addPet
* http://raml.org/
* http://apidocjs.com