swagger-api / swagger-api/swagger-ui

Question regarding the behaviour of `allOf` and `example`

Open
#10,611 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

I was wondering what the expected behavior of allOf with example is. For example I have:

/example:
  get:
    summary: Example
    responses:
      '200':
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/MySchema'
                - example:
                    my_string: "override"
                    my_array:
                      - "override"

components:
  schemas:
    MySchema
      type: object
      properties:
        my_string:
          type: string
        my_array:
          type: array
          items:
            type: string
      example:
        my_string: "original"
        my_array:
          - "original"   

This results in the following example for the response:

{
  "my_string": "override",
  "my_array": [
    "original",
    "override"
  ]
}

Swapping the order within the allOf block results in:

{
  "my_string": "original",
  "my_array": [
    "override",
    "original"
  ]
}

For context, I have a Schema that I want to use in a few different response bodies. Some of these responses need certain values to be slightly different in the examples. I noticed the above behaviour and thought it would be convenient, although I want to make sure that this is expected / supported.

I'm also unsure if this is something specific to swagger-ui or if it's part of the OpenAPI spec, so apologies if I' have asked in the wrong place.

Thanks in advance :)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or entry points are mentioned. Start by comparing the observed allOf/example behavior with the OpenAPI specification, then trace how Swagger UI generates response examples; done means determining whether the merge behavior is supported and, if not, identifying the expected handling or documentation needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.