swagger-api / swagger-api/swagger-core

"Override" example value when extending a class

Open
#4,863 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

I was wondering if the following is possible:
I have a Name object being reused in different objects:

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(type = "string", example = "Henrik")
public class Name {}

The Name object is used many places, e.g. in an Address object:

import io.swagger.v3.oas.annotations.media.Schema;

public class Address {
  @Schema(description = "The name of a person", 
  public Name name;
  ...
}

The expected output looks like this:

Address:
  name:
    description: "The name of a person"
    type: "string"
    example: "Henrik"

so far so good 😊
Name is also used in the Car object (but here I want to use another example value for the name-property e.g. Audi)

import io.swagger.v3.oas.annotations.media.Schema;

public class Car {
  @Schema(description = "Name of a car", example = "Audi")
  public Name name;
  ...
}

This does not work! Expected outcome is:

Car:
  name:
    description: "The name of a car"
    type: "string"
    example: "Audi"

but instead I get:

Car:
  name:
    description: "The name of a car"
    type: "string"
    example: "Henrik"

So example value defined on the name-property in the Car object is ignored... ☹️

It will only accept the description in Address and Car objects because description is not defined in Name object. It will not accept the "overwriting" of example="Audi" in the Car object. Why is this the case? Is it a feature or a Bug?

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

The issue provides no repository file or test entry point; start by tracing how @Schema metadata is processed for the shared Name type and the Car.name field. Done means a field-level example such as "Audi" overrides the type-level "Henrik" example while the existing descriptions and generated OpenAPI output remain correct.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.