search

Mermade / widdershins

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown
https://mermade.github.io/reslate
MIT License
1.48k stars 321 forks source link

Allow descriptions alongside $ref in schema properties #343

Open CatalinMustata opened 4 years ago

CatalinMustata commented 4 years ago

Is your feature request related to a problem? Please describe. Working a relatively complex API, I feel the need to have schema objects separated from the actual schema, so I'm using references everywhere. In the spirit of reusing as much as possible, schema objects are reused, but even if they have a general description, such general objects have different meanings as different properties.

I'm using hapi-swagger to generate the API definitions (OpenAPI 2.0) and I found a "good" workaround for this by adding a description next to $ref, but that gets stripped when converting to OpenAPI 3.0 - something that makes sense given it's not in the specs.

Describe the solution you'd like I'm expecting this to come at one point, but would it be possible to preempt this somehow and get it working sooner? First and foremost it should be enough to not strip description from a property that has a $ref, although there might be more work after that - not yet sure. I'm willing to work on a PR for this , if need be.

Describe alternatives you've considered I don't see any alternatives, given the fact that information is stripped before I could process it somehow.

MikeRalphson commented 4 years ago

You could start by setting the swagger2openapi refSiblings option to preserve in lib/openapi2.js and see if that helps? I'm not sure which template you expect the sibling description to be output by though. The default behaviour within a schema object is to wrap the description and $ref in an allOf, so you might be able to access the description already that way.

CatalinMustata commented 4 years ago

Wow, setting refSiblings to preserve actually did the job, without any other changes! (I did have a run at overriding templates before I found description was stripped, but I couldn't get widdershins to use my own templates)

MikeRalphson commented 4 years ago

OK, let me see about exposing that option for the next release.