Page MenuHomePhabricator
Create Task
Maniphest T428153

Fix description and example issues for page, revision, search, and file paths in the MediaWiki REST API OAD
Open, In Progress, MediumPublic
Actions

Description

Fix linter issues related to descriptions and examples under the following paths in the MediaWiki REST API OAD (89 issues):

  • /v1/page*
  • /v1/revision*
  • /v1/search*
  • /v1/file*

Additionally, fix description and example issues in the components object in the OAD.

Add descriptions:

  • to response schema properties (wikimedia-response-schema-properties-description)
  • to request bodies; after T427355 is done (wikimedia-requestbody-description)
  • to request body schema properties (wikimedia-requestbody-schema-properties-description)
  • to operations (wikimedia-operation-description)
  • to parameters (wikimedia-paths-parameter-description-customized)

Add examples after T427361, T427360, T424002, T426836 are done:

  • for parameters (wikimedia-paths-parameter-example-exists)
  • for responses (wikimedia-response-example-exists)
  • for request bodies (wikimedia-requestbody-example-exists)
  • for schemas (wikimedia-schema-example-recommended)

When adding or editing descriptions in the OAD, be sure to follow the style guide.

Details

Related Changes in Gerrit:
SubjectAuthorRepoBranchLines +/-
REST: Add parameter examples for OADTriciaburmeistermediawiki/coremaster+24 -3
Rest: Add response and parameter examples for several /v1/revision, search, page paths.Triciaburmeistermediawiki/coremaster+39 -20
REST: Add response examples for /v1/file/../thumbnailsTriciaburmeistermediawiki/coremaster+4 -0
Rest: Add response and parameter examples for several /v1/revision, search, page paths.Triciaburmeistermediawiki/coremaster+24 -8
Rest: Add OAD descriptionsTriciaburmeistermediawiki/coremaster+34 -3
Customize query in gerrit

Related Objects
Search...

Event Timeline

KBach created this task.Jun 4 2026, 12:00 PM
KBach triaged this task as Medium priority.
KBach mentioned this in T427793: Fix linter errors and warnings in the MW REST API OAD.
KineticPelagic moved this task from Incoming (Needs Triage) to To Estimate on the MW-Interfaces-Team board.EditedJun 5 2026, 12:45 AM
KineticPelagic added a project: Tool-wmf-openapi-linter.
KineticPelagic subscribed.

As part of my Clinic Duty rotation, I add a project tag and move this task to "To Estimate" because the task is clear enough to be sized and valuable in our current hypothesis. Our own MediaWiki REST API OAD ought to be a role model!

Thanks for making immediately clear the dependency on the other tasks that should happen first.

KBach updated the task description. (Show Details)Jun 8 2026, 1:09 PM
KBach updated the task description. (Show Details)
KBach renamed this task from Add examples to the MediaWiki REST API OAD to Fix description and example issues for page, revision, search, and file paths in the MediaWiki REST API OAD.Jun 9 2026, 9:26 AM
KBach updated the task description. (Show Details)
KBach moved this task from To Estimate to Radar (other teams work) on the MW-Interfaces-Team board.
KBach added a project: Tech-Docs-Team.Jun 9 2026, 9:28 AM
TBurmeister claimed this task.Mon, Jun 22, 5:13 PM
TBurmeister moved this task from Backlog to In progress on the Tech-Docs-Team board.
TBurmeister changed the task status from Open to In Progress.Mon, Jun 22, 6:42 PM
TBurmeister updated the task description. (Show Details)Mon, Jun 22, 7:03 PM

None of the paths listed in the task description have linter errors for operation descriptions (wikimedia-operation-description)
nor for parameter descriptions (wikimedia-paths-parameter-description-customized), so I checked those boxes as done.

gerritbot added a comment.Thu, Jun 25, 7:17 PM

Change #1305743 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] Rest: Add OAD descriptions

https://gerrit.wikimedia.org/r/1305743

gerritbot added a project: Patch-For-Review.Thu, Jun 25, 7:17 PM
gerritbot added a comment.Wed, Jul 1, 1:32 PM

Change #1305743 merged by jenkins-bot:

[mediawiki/core@master] Rest: Add OAD descriptions

https://gerrit.wikimedia.org/r/1305743

ReleaseTaggerBot added a project: MW-1.47-notes (1.47.0-wmf.10; 2026-07-07).Wed, Jul 1, 2:00 PM
Maintenance_bot removed a project: Patch-For-Review.Wed, Jul 1, 2:32 PM
TBurmeister created subtask T431018: OAD linter gives warnings for missing response examples in RESTBase compatibility properties.Thu, Jul 2, 6:22 PM
gerritbot added a comment.Thu, Jul 2, 8:06 PM

Change #1307234 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] Rest: Add response and parameter examples for several /v1/revision, search, page paths.

https://gerrit.wikimedia.org/r/1307234

gerritbot added a project: Patch-For-Review.Thu, Jul 2, 8:06 PM
KBach removed a subtask: T431018: OAD linter gives warnings for missing response examples in RESTBase compatibility properties.Fri, Jul 3, 5:54 AM
gerritbot added a comment.Tue, Jul 7, 5:51 PM

Change #1308171 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] Rest: Add response and parameter examples for several /v1/revision, search, page paths.

https://gerrit.wikimedia.org/r/1308171

gerritbot added a comment.Tue, Jul 7, 5:54 PM

Change #1307234 abandoned by Triciaburmeister:

[mediawiki/core@master] Rest: Add response and parameter examples for several /v1/revision, search, page paths.

Reason:

Replaced by https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1308171

https://gerrit.wikimedia.org/r/1307234

KBach edited projects, added: MW-Interfaces-Team (MediaWiki-Interfaces-Sprints); removed: MW-Interfaces-Team.Wed, Jul 15, 1:38 PM
KBach moved this task from Committed to Code Review on the MW-Interfaces-Team (MediaWiki-Interfaces-Sprints) board.
gerritbot added a comment.Wed, Jul 15, 2:57 PM

Change #1311067 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] REST: Add response examples for /v1/file/../thumbnails

https://gerrit.wikimedia.org/r/1311067

gerritbot added a comment.Wed, Jul 15, 7:02 PM

Change #1311103 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] REST: Add parameter examples for OAD

https://gerrit.wikimedia.org/r/1311103

Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits