search

Redocly / redoc

📘 OpenAPI/Swagger-generated API Reference Documentation
https://redocly.github.io/redoc/
MIT License
22.88k stars 2.26k forks source link

Add an option to disable default sample #1490

Open aleung opened 3 years ago

aleung commented 3 years ago

When the scheme doesn't come with example, Redoc will automatically generate a sample by properties default value. This default sample isn't useful in most case and it's confusing to reader.

I'd like to write examples which represent real use cases in the OpenAPI definition and leave unimportant responses/responses without sample. But I didn't find a way to disable the sample. It is possible to add global option in the tool, or add OpenAPI extension to disable default sample?

api-sample
RomanHotsiy commented 3 years ago

This makes sense. We can implement such an option. PR would be appreciated.

aleung commented 3 years ago

I dug into the code today and found that the sample is generated by another module openapi-sampler.

https://github.com/Redocly/redoc/blob/4b072be8d1c0dc4f1fa627168eebaed0a0213e08/src/services/models/MediaType.ts#L81

Looks like I can do in this way:

  1. Add Redoc option autoGenerateSamples to control whether generate value for fields which have no example defined in schema. Default to true to keep previous behavior.
  2. Pass this option to OpenAPISampler. The option name could be shorten to autoGenerate.

@RomanHotsiy I hope to hear your opinion before I raise PR to these two projects.