[Feature]: Prevent name clash for identical nested class names

[tbvh]

Feature Description

Duplicate class names are not resolved by the library (see #5016).
One special case of name clashes have to do with nested classes.

We ran into schema-name collisions when two top-level models each define a nested class with the same simple name.

Today the behavior seems to be effectively binary:

• default naming uses the simple class name, for example SiteStop
• fully qualified naming uses the package + class name, for example com.example.TripExport.SiteStop
  The first option causes collisions for nested types with the same simple name.
  The second option avoids collisions, but it exposes package names in the public OpenAPI schema, which is often more verbose than desired.

This feature is a request to include the outer name to prevent name clashes.
For example:
TripExport.SiteStop
PublishedTrip.SiteStop

Use Case

The issue would prevent name clash in this case:

package com.example.demo;

import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class DemoController {

    @GetMapping("/trip")
    public TripExport trip() {
        return null;
    }

    @GetMapping("/published-trip")
    public PublishedTrip publishedTrip() {
        return null;
    }
}

class TripExport {
    public List<SiteStop> siteStops;

    static class SiteStop {
        public String stopId;
    }
}

class PublishedTrip {
    public List<SiteStop> siteStops;

    static class SiteStop {
        public String stopId;
    }
}

Suggested Solution (optional)

The problem can we resolved (or worked around) by implementing implementing a different TypeNameResolver and registering it in a ModelResolver.

   @Bean
    public static ModelResolver createModelResolver(ObjectMapper objectMapper) {
        return new ModelResolver(objectMapper, new NestedTypeNameResolver());
    }

    static final class NestedTypeNameResolver extends TypeNameResolver {
        @Override
        protected String getNameOfClass(Class<?> cls) {
            if (cls.getEnclosingClass() == null) {
                return cls.getSimpleName();
            }

            Deque<String> names = new ArrayDeque<>();
            for (Class<?> current = cls; current != null; current = current.getEnclosingClass()) {
                names.push(current.getSimpleName());
            }
            return String.join(".", names);
        }
    }

Alternatives Considered

The fqn toggle also prevens the collision but includes the full package name in the schema, which was not desired in our case.

[Mattias-Sehlstedt]

Depending on what type of segmentation you have between the domain layer and the api layer a possible solution could be to use @Schema(name = "otherName") on one of the clashing classes. E.g.

class TripExport {
    public List<SiteStop> siteStops;

    @Schema(name = "otherName")
    static class SiteStop {
        public String stopId;
    }
}

class PublishedTrip {
    public List<SiteStop> siteStops;

    static class SiteStop {
        public String stopId2;
    }
}

This should result in:

"OtherName" : {
  "type" : "object",
  "properties" : {
    "stopId" : {
      "type" : "string"
    }
  }
},
"SiteStop" : {
  "type" : "object",
  "properties" : {
    "stopId2" : {
      "type" : "string"
    }
  }
}

rather than:

"SiteStop" : {
  "type" : "object",
  "properties" : {
    "stopId" : {
      "type" : "string"
    }
  }
}

This of course works best if you properly segment domain and api, because it is a bit odd to have @Schema within the domain. But given that the issue even arise, I would assume that it is not the case, because if it was then one would just make sure that the two different SiteStops had different API-representations.

So this could be a way of handling it. And tackling the underlying issue that it is counter-intuitive that the default behavior is that classes that clash results in only one of them being kept is left as the separate issue that you have linked.

[Mattias-Sehlstedt]

As for the feature request, I believe it only only makes sense for the project to offer fqn together with a setting to crash/warn upon collision. Anything outside of that binary "full unique path" and "shortest path possible" should be entirely left to the user by customization with a TypeNameResolver.

Note: I am not affiliated with the project.