Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

External dependency: swagger2openapi loses descriptions on complex objects #2067

Open
davetransom opened this issue Jun 30, 2022 · 1 comment · May be fixed by #2207
Open

External dependency: swagger2openapi loses descriptions on complex objects #2067

davetransom opened this issue Jun 30, 2022 · 1 comment · May be fixed by #2207
Labels
help wanted investigation p3

Comments

@davetransom
Copy link

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?)
@davetransom
Copy link
Author

The kind folks over at OAS-Kit have given some advice on this Mermade/oas-kit#597 (comment)

There is an option (CLI and programmatic) called refSiblings which defines the mode to handle $ref's with sibling properties, the valid values are remove (the default), preserve, and allOf, ...

Testing using refSiblings "preserve" makes the field's description available in the parsed swagger object. It can then be used when constructing a new FieldModel, so instead of displaying the description of the schema, it can now show the description of the field.

I'll do a bit more testing and submit a PR for review.

davetransom added a commit to davetransom/redoc that referenced this issue Nov 16, 2022
@davetransom
Use refSiblings: 'preserve' when converting swagger
f0da3c5 
As per Redocly#2067, `swagger2openapi` needs `refSiblings: 'preserve'` to bring additional fields into the converted open-api object.

This makes the description field available to the `fieldSchema` objects, but it also needs to be merged into the field model to be shown in the UI.
@davetransom davetransom linked a pull request Nov 16, 2022 that will close this issue
Open
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted investigation p3
Projects
None yet
Milestone
No milestone
2 participants
@davetransom @AlexVarchuk