action #70204
open
Expose dedicated API docs to replace "not found" page
Added by livdywan over 4 years ago.
Updated over 4 years ago.
Category:
Feature requests
Description
During the retrospective we were briefly discussing the state of our API docs.
- Our "API documentation" is currently the Not Found page of openQA
- API is documented inline, but very incomplete and not well-maintained
- Actual inline documentation should be used for internal API
- The POD format is not particularly well-suited to REST APIs
- Even to confirm what behaviors are supported or expected is currently non-trivial with many features
- We should pick topics to document and select what we support (e.g. REST API vs. UI-support helpers vs. experimental routes)
- API docs should be published online
Suggestion:
- Slate is a fairly well-established tool
- Markdown is widely supported
- Generated docs should be published on open.qa
- Category set to Feature requests
- Priority changed from Normal to Low
- Target version set to future
It's a nice idea but the existing approach was selected because no better idea was found that would be feasible
Note that if we create inline comments manually we can also maintain a markdown document manually instead. To me the maintenance effort of an extra, manually written markdown document (e.g. using Slate) is not higher than maintaining POD comments. The only difference is where the changes would be made. So we would not need some complicated generator here to improve. So if you had a tool for exporting the Mojolicious routes and POD comments directly into a nicely formatted document in mind: Yes, that would likely not be feasible but we also don't need it to improve.
okurz wrote:
It's a nice idea but the existing approach was selected because no better idea was found that would be feasible
How is the suggested tool not feasible? It's actually a lot more suitable for what we need.
So the source for documentation would be markdown?
I personally would prefer to have something in YAML, from which we can generate Markdown.
Having a data file (or several files) will enable us to do more with it than just generating documentation.
For example automatically generate tests.
Also available in: Atom
PDF