Description

Tags are an optional endpoint grouping mechanism offered by SwaggerUI. Tags do not affect routing, but instead allow related endpoints to be grouped under a sub header/accordion within the documentation. Although we are not currently using them within the MediaWiki APIs, they are utilized within the Wikimedia, Wikidata, and AQS REST APIs.

They are a particularly helpful grouping mechanisms in larger modules. When considering the intended module structure, they can be thought of as sub-modules from a documentation perspective. For example, GrowthExperiments may want separate tags for each of the experiments/features within that extension module to make related endpoints easier to discover and give users an indication that they can/should be used together. Additionally, before the API modules are universally deployed, tags may offer a helpful stop gap/low stakes strawman proposal for what the modules might be in the future.

Because tags are used as a navigation and discovery aid for documentation readers, it is important to make the values translatable so they make sense in the developer's language of choice. This will allow developers to better understand the module areas at a glance before diving into the specific endpoints.

Conditions of acceptance

• 'Tags' may be specified within generated OpenAPI specs so that endpoints may be grouped by helpful headers.
  • To start, before modules are widely rolled out, apply tags at a per extension basis within the MediaWiki API. In other words, the extension (or root path) should be specified as the tag for each extension endpoint group.
  • Determine the best approach to create "default" tags for grouping extension and "modularized" Core APIs (like sitemap), if no other tag name is specified.
  • In addition to the default values, tags should support customizable, human friendly names.
• 'Tag' strings may be translated through translatewiki.

Implementation details

Related gerrit patch with early PoC: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1074525 --> Demonstrates making 'default' string localisable.

Suggestion for PoC: Add tag for 'MediaWiki Core' and 'Extensions' within the 'default' MediaWiki spec.

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.