swagger-api / swagger-api/swagger-core

Allow programmatic model name customization

Open
#4,790 0 comments 0 reactions 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

Introduce a method that can be overriden, or another mechanism, to allow for model name customization. An example would be to have a suffix "Enum" for all enum models resolved as ref.

Doing this with a custom model resolver doesn't work.

public class EnumModelConverter implements ModelConverter {

	@Override
	public Schema<?> resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
		if (chain.hasNext()) {
			if (type.getType() instanceof JavaType javaType) {
				if (javaType.isEnumType()) {
					if (!javaType.getRawClass().getSimpleName().endsWith("Enum")) {
						type.setName(javaType.getRawClass().getSimpleName() + "Enum");
					}
				}
			} else if (type.getType() instanceof Class<?> clazz) {
				if (clazz.isEnum()) {
					if (!clazz.getSimpleName().endsWith("Enum")) {
						type.setName(clazz.getSimpleName() + "Enum");
					}
				}
			}
			return chain.next().resolve(type, context, chain);
		}
		return null;
	}
}

While this seems to work, it fails as soon as you have an enum with a custom name in its Schema annotation.

@Schema(name = "SomeClassStatus")
public enum Status {
    ONE, TWO
}

Proposal:
Add a protected method after https://github.com/swagger-api/swagger-core/blob/3c7b61f7d51bb001ec3bc944229cbc19307d17f5/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java#L213 that allows to customize the name.

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

Start in modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java around the location linked in the issue, and read the ModelConverter resolution flow. Compare the custom resolver example with enums using @Schema(name = "SomeClassStatus"). Done means a supported customization point allows programmatic model naming while preserving explicitly customized schema names.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 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.