media-type-examples-override

Replaces the examples in the corresponding file.

API design principles

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" a new examples over the source so that as the source changes, the modifications can be reapplied.

Configuration

Option Type Description
operationIds object 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.

Example of a configuration:

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

Examples

Given this definition with example:

Copy
Copied
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
paths:
  '/GETUser/{userId}':
    summary: getPet
    get:
      operationId: getUserByName
      responses:
        200:
          description: okay
          content:
            application/json:
              examples:
                pet:
                  value:
                    name: test name

Given the file ./pet-examples.yaml with content:

Copy
Copied
Cat:
  value:
    name: example

Given this configuration:

Copy
Copied
decorators:
  media-type-examples-override:
    operationIds:
      PostPets:
        responses:
          '200': ./pet-examples.yaml

The result of the bundle command

Copy
Copied
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
paths:
  '/GETUser/{userId}':
    summary: getPet
    get:
      operationId: getUserByName
      responses:
        200:
          description: okay
          content:
            application/json:
              examples:
                Cat:
                  value:
                    name: example

Related decorators

Resources