`media-type-examples-override` decorator

[adamaltman]

Is your feature request related to a problem? Please describe.

To solve the same issue we solved with other decorators.

Most developers are too lazy to define media type examples.

https://github.com/redocly-demo/decorators-demo/pull/1

In the event the OpenAPI file is auto-generated, then there is no reliable way to add examples (without them getting overwritten on the next auto-generation).

Describe the solution you'd like

I'd like to see:

decorators:
  media-type-examples-override:
    operationIds:
      PostPets: ./pet-examples.yaml

Describe alternatives you've considered None - I am open to ideas.

[IgorKarpiuk]

@adamaltman What should we do if we have few media type examples in one operation?

For example:

responses:
        200:
          description: json
          content:
            application/json:
              examples:
                 test1:
                   value:
                     a: test1
                     b: 35
        201:
          description: xml
          content:
            application/xml:
              examples:
                test2:
                  value:
                   a: test2

[tatomyr]

@adamaltman , @RomanHotsiy any thoughts?

[RomanHotsiy]

There is also request body example.

I'm not sure. @adamaltman what was your idea about the format of ./pet-examples.yaml file? Was it supposed to have multiple examples somehow?

[adamaltman]

Yes, it can have multiple examples. However, that's a good question. It needs to target the response code or the request media type.

So maybe it should be like this:

decorators:
  media-type-examples-override:
    operationIds:
       PostPets:
          request: 
              application/json: ./pet-examples.yaml
          responses: 
            '200': ./pet-examples.yaml
            '400': ./pet-errors-examples.yaml

EDITED

[IgorKarpiuk]

@adamaltman How we should handle $ref in responses?

responses:
        200:
          $ref: '#/components/responses/okay'
        400:
         $ref: '#/components/responses/badRequest'

1. We can override examples directly inside components section But may be a problem with links to one response in several places. For example:

responses:
        200:
          $ref: '#/components/responses/okay200'
        400:
         $ref: '#/components/responses/okay200'

2. We can resolve the refs and override the examples already in the right places. But the references needed in the decorator will be resolved and all others will not

[IgorKarpiuk]

I implemented the second option because it looks more secure