Change Details

The Wikimedia OpenAPI Linter requires endpoints to be grouped by [tags](https://spec.openapis.org/oas/v3.0.html#tag-object), so the MediaWiki REST API OpenAPI docs should support defining tags and assigning them to individual paths. Both the tag `name` and `description` should be translatable. Example: ``` ... "tags": [ { "name": "Math" } ], ... "paths": { "/media/math/check/{type}": { "post": { "tags": [ "Math" ], ... ``` The OpenAPI spec also supports a `description` field and an `externalDocs` object for tags. In my opinion, these would be nice to have but are lower priority and should be considered outside the scope of this task.

[Tags in OpenAPI descriptions](https://spec.openapis.org/oas/v3.0.html#tag-object) 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" ], ... ``` [[ https://gitlab.wikimedia.org/repos/technical-documentation/openapi-description-example/-/blob/main/oad-expanded.yaml?ref_type=heads#L58 | OAD example #1 ]], [[ https://gitlab.wikimedia.org/repos/technical-documentation/openapi-description-example/-/blob/main/oad-expanded.yaml?ref_type=heads#L79 | 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.

The Wikimedia[Tags in OpenAPI Linter requires endpoints to be grouped by [tagdescriptions](https://spec.openapis.org/oas/v3.0.html#tag-object) 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, so the MediaWiki REST API OpenAPI docs should support defining tags and assigning them to individual pathsoperations. Both the tag `name` (required field) and `description`on` (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" ], ... ``` [[ https://gitlab.wikimedia.org/repos/technical-documentation/openapi-description-example/-/blob/main/oad-expanded.yaml?ref_type=heads#L58 | OAD example #1 ]], [[ https://gitlab.wikimedia.org/repos/technical-documentation/openapi-description-example/-/blob/main/oad-expanded.yaml?ref_type=heads#L79 | OAD example #2 ]] The OpenAPI spec also supports a `description` field and anthe `externalDocs` object for tags. In my opinion, theseThis field would be nice to have but areis lower priority and shouldcan be considered outside the scope of this task.