CODEWITHSUNDEEP
swaggeropenapi
Darth_Sygnious
Darth_Sygnious

Reputation: 558

OpenAPI: Can you use sub-components inside examples?

OpenAPI version: 3.0.1.

I'm working on the examples-section of an OpenAPI-specification.

I am familiar with components, and I know that I can define examples-components that are to be used at root level. For instance:

...
  examples:
    Students:
      $ref: '#/components/examples/students'

In my case, however, I am working with only one endpoint that may give huge and varying content in the response. Therefore I'm working with several different examples, and creating a component for one full example is of no use to me.

On the other hand, I'm reusing sub-parts in several examples, and I would like to create components based on these sub-parts.

Something like this simplified example, where I have a list of students with the same teacher and postal address:

...
  examples:
    Students:
      value:
        - name: James Bond
          teacher: 
            $ref: '#/components/examples/teacherTrunchbull'
          postalAddress:
            $ref: '#/components/examples/london'
        - name: Bilbo Baggins
          teacher: 
            $ref: '#/components/examples/teacherTrunchbull'
          postalAddress:
            $ref: '#/components/examples/london'
        -  .......
...
components:
  examples:
    teacherTrunchbull:
      (value: ??)
        name: Agatha Trunchbull
        address: School street 34
        postalAddress:
          number: 5201
          name: London 
    london:
      (value: ??)
        number: 5201
        name: London

For the record, I do know that examples needs to contain "value" as field, but all I can manage to do with it is to create a full example, not sub-components for my examples.

I do suspect that OpenAPI version 3.0.1. does not support what I am asking about, in which case, only this works:

...
  examples:
    Students:
      $ref: '#/components/examples/students'

If this is the case, please confirm it so that we can call it case closed. But if what I am asking about does exist, how then do I do it?

Many thanks for your answers.

Upvotes: 1

Views: 597

Answers (1)

Software2
Software2

Reputation: 2738

example does not support using $ref in this manner.

From this bug thread:

What we meant here (and if needed, can clarify further) is that the value given here is the actual value of the example. It is not to be further parsed by tooling. So documentation or mocking services should not try to parse the $ref's before further 'using' them.

The reason behind is exactly $ref's. We can't distinguish when the end user would want to use $ref as a resolved reference and when they'd want to use it as a literal value (which is a very valid case). As such, we decided that the examples would be non-parsed literal values. At the moment, there's no way to have parsable examples, as external examples are literal values as well.

Upvotes: 2

Related Questions