Add a paths.[path].[method].summary field for each endpoint in the MediaWiki REST API OpenAPI spec with a short endpoint name. Endpoint names can be sourced from h3 headings in the MediaWiki REST API reference.

Background

In REST API documentation, it is essential for each endpoint to have a short name that can be used in navigation to helps readers differentiate between endpoints easily. The OpenAPI 'Operation Object' allows these short-hand descriptions to be populated in the summary field, along with longer form descriptions in the description field.

For example, consider these two endpoints from the Analytics API

• GET /edited-pages/aggregate/{project}/{editor-type}/{page-type}/{activity-level}/{granularity}/{start}/{end}
• GET /edited-pages/new/{project}/{editor-type}/{page-type}/{granularity}/{start}/{end}

These paths are not easy for readers to understand and differentiate, so they can't be used in endpoint navigation. Instead, the OpenAPI spec for this API includes a summary for each endpoint:

• Get number of edited pages
• Get number of new pages

When considering SwaggerUI specifically, the summary field is what adds the human friendly text to the collapsed accordion view, whereas the description is intended to be slightly longer form and is only visible if you expand the accordion. We want to add the summaries to improve clarity around what each endpoint is for, without folks needing to expand the accordion every time.

You can see that these summaries are much easier to understand and form a key part of readers' ability to navigate between endpoints.

Other Summary examples can be found in the RESTbase specs.
RESTbase example:

MW REST current state (missing the summary):

Implementation details

If you look in our spec, the description is populated, but the summary is not (see spec screenshot). We want to add the summary to every MW REST API endpoint, which basically means everything that we own under /v1.

Reference: Summaries are listed as "endpoint names" in the list of essential elements of REST API documentation on mediawiki.org. In the screenshot below, the orange box represents what we should add as the summary, vs the green box which reflects what is currently used for the description.

Summaries should be added to every MW REST API endpoint that MWI owns. That applies to every endpoint under the main /v1 route when looking at the REST Sandbox. A specific list of endpoints is below:

• GET /v1/page/{title}/history
• GET /v1/page/{title}/history/counts/{type}
• GET /v1/revision/{from}/compare/{to}
• GET /v1/revision/{id}
• GET /v1/revision/{id}/html
• GET /v1/revision/{id}/with_html
• GET /v1/revision/{id}/bare
• GET /v1/search
• GET /v1/search/page
• GET /v1/search/title
• GET /v1/page/{title}/links/language
• GET /v1/page/{title}
• PUT /v1/page/{title}
• GET /v1/page/{title}/bare
• GET /v1/page/{title}/html
• GET /v1/page/{title}/with_html
• GET /v1/page/{title}/links/media
• GET /v1/file/{title}
• POST /v1/page
• POST /v1/transform/wikitext/to/html/{title}/{revision}
• POST /v1/transform/html/to/wikitext/{title}/{revision}
• GET /v1/transform/wikitext/to/lint/{title}/{revision}
• POST /v1/transform/wikitext/to/lint/{title}/{revision}
• POST /v1/transform/wikitext/to/html
• POST /v1/transform/wikitext/to/html/
• POST /v1/transform/html/to/wikitext
• POST /v1/transform/html/to/wikitext/
• POST /v1/transform/wikitext/to/lint
• POST /v1/transform/wikitext/to/lint/
• POST /v1/transform/wikitext/to/html/{title}
• POST /v1/transform/wikitext/to/html/{title}/
• POST /v1/transform/html/to/wikitext/{title}
• POST /v1/transform/html/to/wikitext/{title}/
• GET /v1/transform/wikitext/to/lint/{title}
• POST /v1/transform/wikitext/to/lint/{title}
• GET /v1/transform/wikitext/to/lint/{title}/
• POST /v1/transform/wikitext/to/lint/{title}/