Redocly/redoc

External dependency: swagger2openapi loses descriptions on complex objects

Open

#2.067 geöffnet am 30. Juni 2022

Auf GitHub ansehen
 (1 Kommentar) (2 Reaktionen) (0 zugewiesene Personen)TypeScript (21.877 Stars) (2.272 Forks)batch import
help wantedinvestigationp3

Beschreibung

I've created an issue Mermade/oas-kit#597 over at swagger2openapi regarding an anomaly with converting field descriptions on swagger 2.0 documents.

I wanted to lodge it here as well in the advent of a fix.

The the descriptions on fields for complex objects are overwritten with the description of the object definition itself, and losing context for the user e.g. instead of displaying "The weight (in kg)..." and "The volume (in m3)..." of a reusable measurement object definition, it displays "A generic measurement." for both fields.

image

(I'll come back to update this as the issue progresses, if this is the right way to handle things?)

Contributor Guide

Tech Stack
typescript
Domain
apidocumentation
Issue Type
bug
SchwierigkeitGeschätzte Implementierungsschwierigkeit für neue Contributors, von 1 für sehr kleine Änderungen bis 5 für Expertenarbeit.
3
Geschätzte ZeitEin grober Zeitrahmen, um zu recherchieren, zu implementieren, zu testen und einen Pull Request vorzubereiten.
1-3 hours
AktivitätsstatusWie verfügbar das Issue gerade wirkt: frisch, aktiv, stale, blockiert oder wartet auf Maintainer-Input.
fresh
KlarheitWie klar das Issue die erwartete Änderung, Akzeptanzkriterien und den nächsten Schritt erklärt.
mostly clear
Voraussetzungen
basic understanding of OpenAPI/Swagger specs
EinsteigerfreundlichkeitEin Score von 1 bis 100, der schätzt, wie zugänglich dieses Issue für First-Time Contributors ist.
50
Research-Richtung
Investigate the upstream dependency issue Mermade/oas kit#597 to understand how swagger2openlayers loses descriptions. Then trace how Redoc processes descriptions from converted specs, focusing on the display logic for complex objects. Check if Redoc can work around the upstream bug by preserving descriptions from the original Swagger document or by applying a patch.