OpenAPI docs incorrectly show response examples for empty response bodies
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	Jakob_WMDE
	Jan 2 2024, 4:18 PM

Description

Some responses are expected to have an empty response body and in such cases our docs should simply not show examples for response bodies. They currently show an example saying "string" which is confusing.

Example:

in https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/items/getItem

This was likely caused by an update to the latest version of swagger-ui, the software that generates the docs based on the spec.

Possible solutions:

attempt to fix upstream. https://github.com/swagger-api/swagger-ui/issues/9199 is the relevant issue.
work around it somehow

Details

	Subject	Repo	Branch	Lines +/-
	REST: Update swagger-ui 5.9.4 -> 5.17.14	mediawiki/extensions/Wikibase	master	+20 -20

Customize query in gerrit

Event Timeline

Jakob_WMDE created this task.Jan 2 2024, 4:18 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 2 2024, 4:18 PM

Jakob_WMDE renamed this task from OpenAPI docs show response examples where there shouldn't be any to OpenAPI docs incorrectly show response examples for empty response bodies.Jan 2 2024, 4:18 PM

Jakob_WMDE moved this task from Tech backlog to Backlog on the Wikibase Product Platform Team WPP board.

Jakob_WMDE updated the task description. (Show Details)Jan 2 2024, 4:20 PM

Jakob_WMDE updated the task description. (Show Details)Jan 2 2024, 4:25 PM

Ifrahkhanyaree_WMDE added a project: Wikibase REST API (WPP).Jan 3 2024, 10:20 AM

Apparently this has been fixed in v5.11.10 of the swagger-ui: https://github.com/swagger-api/swagger-ui/issues/9199#issuecomment-1981110616
We should try updating to see if this fixes our issue.