Project

General

Profile

action #70204

Expose dedicated API docs to replace "not found" page

Added by cdywan 11 months ago. Updated 11 months ago.

Status:
New
Priority:
Low
Assignee:
-
Category:
Feature requests
Target version:
Start date:
2020-08-18
Due date:
% Done:

0%

Estimated time:
Difficulty:

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

History

#1 Updated by okurz 11 months ago

  • 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

#2 Updated by mkittler 11 months ago

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.

#3 Updated by cdywan 11 months ago

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.

#4 Updated by tinita 11 months ago

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