Page MenuHomePhabricator

Support tags in MediaWiki REST API OpenAPI descriptions
Closed, DuplicatePublic

Description

Tags in OpenAPI descriptions provide a mechanism for grouping operations. They are particularly useful for APIs with many endpoints, so the MediaWiki REST API OpenAPI docs should support defining them, and assigning them to individual operations. Both the tag name (required field) and description (recommended by the linter in a message with severity info) should be translatable.

Example:

...
 "tags": [
    {
      "name": "Math"
    }
  ],
...
"paths": {
    "/media/math/check/{type}": {
      "post": {
        "tags": [
          "Math"
        ],
...

OAD example #1, OAD example #2

The OpenAPI spec also supports the externalDocs object for tags. This field would be nice to have but is lower priority and can be considered outside the scope of this task.