Give greater control over API doc input and avoid broken docs.
Review Request #52 — Created Aug. 25, 2022 and updated
Information | |
---|---|
guest8114 | |
Review Board | |
f62a2b2... | |
Reviewers | |
demo | |
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 of `http`. Testing Done: 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. Reviewed at https://reviews.reviewboard.org/r/12540/