Give greater control over API doc input and avoid broken docs.
Review Request #12540 — Created Aug. 16, 2022 and submitted — Latest diff uploaded
Over time, the
webapidocs
code has changed to accommodate changes in
our API, and so has our test data. These changes have largely been done
without properly auditing the resulting documentation, and unfortunately
starting in Review Board 4, we ended up with a lot of bad, mostly-empty
payloads and broken docs due to new objects in the database for the DVCS
work that took precedence over other curated docs. This has further
worsened with the changes for Review Board 5.This change redoes a lot of how the doc generation code decides which
objects to pick. It still has the introspection capabilities, but now
specific docs can provide values for URLs to allow examples to be based
on specific entries. That means we can continue to augment the
documentation database data without further regressions.The 4.0 release also introduced features that the documentation is still
saying must be turned on for use. That's very misleading. We now only
show a notice if a feature is listed as off by default.Several examples with bad data would show up, and some would not. Same
with links. We worked around this with options for the directive to turn
these off, but with the fixes in this release, we no longer need to do
that for most resources.Bad assumptions that led to hiding documentation for resources without
models have been fixed.Examples now include the HTTP status code, and no longer show the wrong
payload if the response is a redirect.And finally, the example URL now uses
https
instead ofhttp
.
Generated the docs and carefully went through every single page. Made sure
all URLs and examples were correct.This does have a counterpart involving new database data, which will go
in separately.