{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"media-type-examples-override","__idx":0},"children":["media-type-examples-override"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replaces the request body or response examples in an API description with the contents of a specified file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sometimes developers generate OpenAPI and the examples need to be added or improved after the fact."," ","This generally happens when you have no permission to edit the source."," ","This decorator provides a way to \"overlay\" new examples over an API description so that as the API changes, the modifications can be reapplied."," ","It replaces the whole ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," section of the given media type for the request body or response status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["operationIds"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Object consisting of operationIds as keys, and object as a value that containing the request and responses keys and example`s paths as values."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example of a configuration file using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["media-type-examples-override"]}," decorator is shown below:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n  media-type-examples-override:\n    operationIds:\n      updateSpecialEvent:\n        request:\n          application/json: ./private-event-examples.yaml\n      getMuseumHours:\n        responses:\n          '200':\n            application/json: ./opening-hours-examples.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestBody"]}," media type example by using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request"]}," key in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},"."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," section in the API description is wholly replaced by the contents of the file you reference."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace a response media type example for a specific status by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responses"]}," and then the desired status in your configuration file."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," section for that response status is replaced by the contents of the file specified."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," field is replaced; the response status must already exist and be defined in the API description."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given this API description with example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"openapi: 3.1.0\ninfo:\n  title: Redocly Museum API\n  description: An imaginary, but delightful Museum API for interacting with museum services and information. Built with love by Redocly.\n  contact:\n    url: 'https://redocly.com/docs/cli/'\nservers:\n  - url: 'https://api.fake-museum-example.com/v1'\npaths:\n  /museum-hours:\n    get:\n      summary: Get museum hours\n      operationId: getMuseumHours\n      responses:\n        '200':\n          description: Success\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/GetMuseumHoursResponse'\n              examples:\n                default_example:\n                  $ref: '#/components/examples/GetMuseumHoursResponseExample'\n        '400':\n          description: Bad request\n        '404':\n          description: Not found\ncomponents:\n  schemas:\n    GetMuseumHoursResponse:\n      description: List of museum operating hours for consecutive days.\n      type: array\n      items:\n        $ref: '#/components/schemas/MuseumDailyHours'\n    MuseumDailyHours:\n      description: Daily operating hours for the museum.\n      type: object\n      properties:\n        date:\n          type: string\n          description: Date the operating hours apply to.\n          example: 2023-12-31\n        timeOpen:\n          type: string\n          description: Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).\n          example: 09:00\n        timeClose:\n          description: Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).\n          type: string\n          example: 18:00\n    GetMuseumHoursResponseExample:\n      summary: Get hours response\n      value:\n        - date: '2024-06-18'\n          timeOpen: '09:00'\n          timeClose: '18:00'\n        - date: '2024-06-19'\n          timeOpen: '09:00'\n          timeClose: '18:00'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given the file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./opening-hours-examples.yaml"]}," with content:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"GetMuseumHoursResponseExampleShort:\n  summary: Short-term opening hours\n  value:\n    - date: '2023-09-11'\n      timeOpen: '09:00'\n      timeClose: '18:00'\n    - date: '2023-09-12'\n      timeOpen: '09:00'\n      timeClose: '18:00'\nGetMuseumHoursResponseExampleClosed:\n  summary: The museum is closed\n  value: []\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given this configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n  remove-unused-components: on\n  media-type-examples-override:\n    operationIds:\n      getMuseumHours:\n        responses:\n          '200':\n            application/json: ./opening-hours-examples.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove-unused-components"]}," decorator here, the bundle also removes the overwritten example from the components section of the API description."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The result of the bundle command ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly bundle openapi.yaml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"openapi: 3.1.0\ninfo:\n  title: Redocly Museum API\n  description: An imaginary, but delightful Museum API for interacting with museum services and information. Built with love by Redocly.\n  contact:\n    url: https://redocly.com/docs/cli/\nservers:\n  - url: https://api.fake-museum-example.com/v1\npaths:\n  /museum-hours:\n    get:\n      summary: Get museum hours\n      operationId: getMuseumHours\n      responses:\n        '200':\n          description: Success\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/GetMuseumHoursResponse'\n              examples:\n                GetMuseumHoursResponseExampleShort:\n                  summary: Short-term opening hours\n                  value:\n                    - date: '2023-09-11'\n                      timeOpen: '09:00'\n                      timeClose: '18:00'\n                    - date: '2023-09-12'\n                      timeOpen: '09:00'\n                      timeClose: '18:00'\n                GetMuseumHoursResponseExampleClosed:\n                  summary: The museum is closed\n                  value: []\n        '400':\n          description: Bad request\n        '404':\n          description: Not found\ncomponents:\n  schemas:\n    GetMuseumHoursResponse:\n      description: List of museum operating hours for consecutive days.\n      type: array\n      items:\n        $ref: '#/components/schemas/MuseumDailyHours'\n    MuseumDailyHours:\n      description: Daily operating hours for the museum.\n      type: object\n      properties:\n        date:\n          type: string\n          description: Date the operating hours apply to.\n          example: '2023-12-31'\n        timeOpen:\n          type: string\n          description: Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).\n          example: '09:00'\n        timeClose:\n          description: Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).\n          type: string\n          example: '18:00'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["media-type-examples-override"]}," decorator to maintain rich example sets in separate YAML or JSON files, and add them to your API description to give more complete or informative examples to your users."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-decorators","__idx":4},"children":["Related decorators"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/operation-description-override"},"children":["operation-description-override"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/tag-description-override"},"children":["tag-description-override"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/remove-unused-components"},"children":["remove-unused-components"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":5},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/decorators/common/info-description-override.ts"},"children":["Decorator source"]}]}]}]},"frontmatter":{},"tagList":["admonition"],"title":"media-type-examples-override","lastModified":"2026-05-18T14:03:00.000Z"}