search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.67k stars 9.07k forks source link

Proposal - extract Swagger Examples into separate files of mappings. #1533

Closed ptoora closed 6 months ago

ptoora commented 6 years ago

Examples (plus swagger) can be used as the basis for stubs/mocks. If we can separate these out from the Swagger files, ideally in a Wiremock Mapping style, then the combination of the Swagger plus the Mappings will mean that, with existing open source offerings (eg. https://github.com/telegraph/swagger-stub), we can stand-up a stub/mock very quickly. This will also neatly draw design and implementation closer.

darrelmiller commented 6 years ago

Examples can be separated out into a different file using the externalValue property of the example object. Is this sufficient for your needs?

MikeRalphson commented 5 years ago

Ping @ptoora

kscheirer commented 1 year ago

I am evaluating this as a possible use case for overlays, https://github.com/OAI/Overlay-Specification/discussions/9.

Possibly overlays could help here, examples could be defined in overlay file, that would technically meet the requirement of having examples in a separate file. Not sure that is any better than using externalValue mentioned previously though.

Tooling could also be used (for ex jq) to parse a contract quickly and extract/transform the examples, to a separate file if need be. This makes overlay the wrong way to handle this use case.

handrews commented 6 months ago

It sounds like externalValue was the main answer, and further work is taking place in Overlays. I'm going to close this as answered / part of another project.