• 
      

    Give greater control over API doc input and avoid broken docs.

    Review Request #12540 — Created Aug. 16, 2022 and submitted — Latest diff uploaded

    Information

    Review Board
    release-5.0.x

    Reviewers

    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.

    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.

    Commits

    Files