Schema description of one field overrides descriptions of other fields of same class

[pchmieli]

Let's take an example of two simple classes:

public class GeoPointDto {

	@Schema(description = "Longitude of geo point ( -180, 180 >")
	private double lon;

	@Schema(description = "Latitude of geo point < -90, 90 >")
	private double lat;
}

public class RouteDto {

	@Schema(description = "Point where the route begins")
	private GeoPointDto startPoint;

	@Schema(description = "Intermediate point of the route")
	private GeoPointDto intermediatePoint;

	@Schema(description = "Point where the route ends")
	private GeoPointDto endPoint;
}

Expected behavior is to have three fields inside RouteDto with different descirption each.
Actual behavior is that all fields has same description = "Point where the route ends" which is the description of third field.

UI:

JSON:

  "components" : {
    "schemas" : {
      "RouteDto" : {
        "type" : "object",
        "properties" : {
          "startPoint" : {
            "$ref" : "#/components/schemas/GeoPointDto"
          },
          "intermediatePoint" : {
            "$ref" : "#/components/schemas/GeoPointDto"
          },
          "endPoint" : {
            "$ref" : "#/components/schemas/GeoPointDto"
          }
        }
      },
      "GeoPointDto" : {
        "type" : "object",
        "properties" : {
          "lon" : {
            "type" : "number",
            "description" : "Longitude of geo point ( -180, 180 >",
            "format" : "double"
          },
          "lat" : {
            "type" : "number",
            "description" : "Latitude of geo point < -90, 90 >",
            "format" : "double"
          }
        },
        "description" : "Point where the route ends"
      }
    }
  }

[devoto13]

According to the specification all properties except $ref in the object should be ignored, so I guess it is unsolvable problem for the current OpenAPI Specification. Unless we inline the schema instead of using a reference, which is undesired for a lot of other reasons.

I would say that it is more consistent behavior to always ignore (maybe with a warning) any properties of the @Schema annotation on the object property when the property type is a reference to another schema. Overriding properties in the referenced schema leads to weird behavior when referenced schema is used multiple times. I understand why current behavior is used as it allows things to kinda work for nested objects used only once... Not sure how to fix this bug with the current specification.

Looks like the restriction on the $ref + other properties was lifted in the latest draft, but it will probably not get adopted by OpenAPI specification any time soon.

[Cybermite]

Looks like the restriction on the $ref + other properties was lifted in the latest draft, but it will probably not get adopted by OpenAPI specification any time soon.

Looks like it was adopted in 3.1.0: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-19

[DepickereSven]

@Cybermite

It's indeed adopted in 3.1.0
Reference: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject

[rainer-wei]

This issue still exists in 2.2.15 at least.

[arvsr1988]

is the issue fixed in OAS 3.1 or do we need to do something different in the code?

public class RouteDto {

	@Schema(description = "Point where the route begins")
	private GeoPointDto startPoint;

	@Schema(description = "Intermediate point of the route")
	private GeoPointDto intermediatePoint;

	@Schema(description = "Point where the route ends")
	private GeoPointDto endPoint;
}

[andrejb-dev]

Still issue with swagger-ui 5.2.0, camel-openapi 4.3.0 and springdoc-openapi-starter 2.2.0. Not sure which is in effect.
But I used this simple workaround

public class GeoPointDto {

	@Schema(description = "Longitude of geo point ( -180, 180 >")
	private double lon;

	@Schema(description = "Latitude of geo point < -90, 90 >")
	private double lat;

	public static class Start extends GeoPointDto {}
	public static class Intermediate extends GeoPointDto {}
	public static class End extends GeoPointDto {}
}

public class RouteDto {

	@Schema(description = "Point where the route begins")
	private GeoPointDto.Start startPoint;

	@Schema(description = "Intermediate point of the route")
	private GeoPointDto.Intermediate intermediatePoint;

	@Schema(description = "Point where the route ends")
	private GeoPointDto.End endPoint;
}

[pedrohubner]

Me and @garciagiovane found the solution at this documentation at section 13.74. How can i define different schemas for the same class?.

If we document variables that have the same type, and they have different schemas with different descriptions, at compile time the last variable description will overwrite the other ones because they have the same type.

[jochenberger]

See #3561

[jochenberger]

Following OAI/OpenAPI-Specification#2033, would it be possible to generate something like this?

  "components" : {
    "schemas" : {
      "RouteDto" : {
        "type" : "object",
        "properties" : {
          "startPoint" : {
            "description" : "Point where the route begins",
            "allOf" : [
              "$ref" : "#/components/schemas/GeoPointDto"
            ]
          },
          "intermediatePoint" : {
            "description" : "Intermediate point of the route",
            "allOf" : [
              "$ref" : "#/components/schemas/GeoPointDto"
            ]
          },
          "endPoint" : {
            "description" : "Point where the route ends",
            "allOf" : [
              "$ref" : "#/components/schemas/GeoPointDto"
            ]
          }
        }
      },
      "GeoPointDto" : {
        "type" : "object",
        "properties" : {
          "lon" : {
            "type" : "number",
            "description" : "Longitude of geo point ( -180, 180 >",
            "format" : "double"
          },
          "lat" : {
            "type" : "number",
            "description" : "Latitude of geo point < -90, 90 >",
            "format" : "double"
          }
        }
      }
    }
  }

[jochenberger]

Unfortunately, there doesn't seem to be a way to have the schema generated like that. The allOf in the @Schema annotation is being ignored.

[ghostg00]

I also encountered the same problem, I don't know when it can be solved? As for the method mentioned above using subclassing, I feel it is not a good solution.

[martinitus]

I just wrote a unit test for this and it actually worked. At least the default ModelConverter adds the descriptions correctly when configured to used OpenAPI v3.1.

package io.swagger.v3.core.resolving.v31;

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverterContextImpl;
import io.swagger.v3.core.jackson.ModelResolver;
import io.swagger.v3.core.matchers.SerializationMatchers;
import io.swagger.v3.core.resolving.SwaggerTestBase;
import org.testng.annotations.Test;

public class Ticket3900Test extends SwaggerTestBase {

    @Test
    public void testArraySchemaItemsValidation() {
        final ModelResolver modelResolver = new ModelResolver(mapper()).openapi31(true);
        final ModelConverterContextImpl context = new ModelConverterContextImpl(modelResolver);
        io.swagger.v3.oas.models.media.Schema model = context.resolve(new AnnotatedType(Route.class));
        SerializationMatchers.assertEqualsToYaml31(model, "type: object\n" +
                "properties:\n" +
                "  startPoint:\n" +
                "    $ref: '#/components/schemas/GeoPoint'\n" +
                "    description: Point where the route begins\n" +
                "  intermediatePoint:\n" +
                "    $ref: '#/components/schemas/GeoPoint'\n" +
                "    description: Intermediate point of the route\n" +
                "  endPoint:\n" +
                "    $ref: '#/components/schemas/GeoPoint'\n" +
                "    description: Point where the route ends");
    }

    private static class GeoPoint {

        @io.swagger.v3.oas.annotations.media.Schema(description = "Longitude of geo point ( -180, 180 >")
        public double lon;

        @io.swagger.v3.oas.annotations.media.Schema(description = "Latitude of geo point < -90, 90 >")
        public double lat;
    }

    private static class Route {
        @io.swagger.v3.oas.annotations.media.Schema(description = "Point where the route begins")
        public GeoPoint startPoint;

        @io.swagger.v3.oas.annotations.media.Schema(description = "Intermediate point of the route")
        public GeoPoint intermediatePoint;

        @io.swagger.v3.oas.annotations.media.Schema(description = "Point where the route ends")
        public GeoPoint endPoint;
    }
}

For the folks that came here from springdoc-openapi. When setting the OpenAPI version to 3.1 in the configuration bean, it seems to work as expected. See e.g. changes made here: springdoc/springdoc-openapi#2833

[frantuma]

$ref siblings are alloweded In OpenAPI 3.1.x and supported by setting related config.

In OpenAPI 3.0.x different configuration options are available in 2.2.24+ releases

[jochenberger]

TBH, I don't see a way to configure things for OpenAPI 3.0. My proposed solution #3900 (comment) cannot be generated with Swagger.