feat(docservice): Support Jackson polymorphism annotations #6370

YoungHoney · 2025-08-26T08:12:43Z

Motivation

This pull request implements support for Jackson's polymorphism annotations (@JsonTypeInfo, @JsonSubTypes) in DocService, as requested in the community (issue #6313). Currently, DocService does not correctly generate documentation for annotated services that use inheritance in their DTOs, leading to incomplete specifications. This change adds a new DescriptiveTypeInfoProvider to resolve these polymorphic types and generate accurate JSON Schemas.

However, this feature has uncovered significant and complex build stability issues when running a full parallel build (./gradlew clean build --parallel). This PR serves as both the implementation of the feature and a concrete test case for discussing the build instability it triggers.

Modifications

Added JacksonPolymorphismTypeInfoProvider: A new provider that uses pure Java reflection to safely inspect @JsonTypeInfo and @JsonSubTypes annotations. It is registered via Java's SPI mechanism to be discoverable by DocService.
Added DiscriminatorInfo: A new data class to hold polymorphism metadata extracted from the annotations.
Consolidated Type Utilities: General-purpose type conversion logic (e.g., toTypeSignature) was moved from a separate DocServiceTypeUtil into AnnotatedDocServicePlugin for better cohesion.
Updated StructInfo: Modified to include oneOf and discriminator fields to carry polymorphism information.
Updated JsonSchemaGenerator: The generator now recognizes the new fields in StructInfo and correctly produces JSON Schema with oneOf and discriminator properties.
Added PolymorphismDocServiceExample: A new example service to demonstrate and manually verify the feature.

Result

DocService can now correctly generate documentation for annotated services that use polymorphic types with Jackson. The resulting JSON Schema will contain the appropriate oneOf and discriminator fields.
Known Issue: This change is known to trigger build instability in the project's CI environment. A detailed summary of the investigation is provided here : Request Guidance on Build Issues in my feature branch #6369

Example usage

also, you can try this at PolymorphismDocServiceExample

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "species")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Dog.class, name = "dog"),
    @JsonSubTypes.Type(value = Cat.class, name = "cat")
})
interface Animal {
    // ...
}

"structs" : [ {
    "name" : "example.armeria.server.animal.PolymorphismDocServiceExample$Animal",
    "fields" : [ ],
    "descriptionInfo" : {
      "docString" : "",
      "markup" : "NONE"
    },
    "oneOf" : [ "example.armeria.server.animal.PolymorphismDocServiceExample$Dog", "example.armeria.server.animal.PolymorphismDocServiceExample$Cat" ],
    "discriminator" : {
      "propertyName" : "species",
      "mapping" : {
        "dog" : "#/definitions/example.armeria.server.animal.PolymorphismDocServiceExample$Dog",
        "cat" : "#/definitions/example.armeria.server.animal.PolymorphismDocServiceExample$Cat"
      }
    }

CLAassistant · 2025-08-26T08:12:54Z

All committers have signed the CLA.

minwoox · 2025-08-28T00:56:57Z

However, this feature has uncovered significant and complex build stability issues when running a full parallel build (./gradlew clean build --parallel).

I will investigate it.
It seems like your changes aren't related to the failure, so please feel free to change the draft status when you are ready.

Adds a new `JacksonPolymorphismTypeInfoProvider` to generate correct JSON Schemas with `oneOf` and `discriminator` for polymorphic types annotated with `@JsonTypeInfo` and `@JsonSubTypes`.

core/src/test/java/com/linecorp/armeria/internal/server/annotation/AnnotatedDocServiceTest.java

...test/java/com/linecorp/armeria/internal/server/annotation/AnnotatedDocServicePluginTest.java

...ain/resources/META-INF/services/com.linecorp.armeria.server.docs.DescriptiveTypeInfoProvider

Adds a new `JacksonPolymorphismTypeInfoProvider` to generate correct JSON Schemas with `oneOf` and `discriminator` for polymorphic types annotated with `@JsonTypeInfo` and `@JsonSubTypes`.

codecov · 2025-09-03T01:26:03Z

Codecov Report

❌ Patch coverage is 71.04558% with 108 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.05%. Comparing base (8150425) to head (e7a0237).
⚠️ Report is 175 commits behind head on main.

Files with missing lines	Patch %	Lines
...a/server/animal/PolymorphismDocServiceExample.java	0.00%	42 Missing ⚠️
...ecorp/armeria/server/docs/JsonSchemaGenerator.java	83.69%	13 Missing and 17 partials ⚠️
...necorp/armeria/server/docs/DocServiceTypeUtil.java	84.21%	6 Missing and 6 partials ⚠️
...inecorp/armeria/server/docs/DiscriminatorInfo.java	40.00%	9 Missing ⚠️
...a/com/linecorp/armeria/server/docs/StructInfo.java	57.89%	5 Missing and 3 partials ⚠️
...rver/docs/JacksonPolymorphismTypeInfoProvider.java	81.08%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #6370      +/-   ##
============================================
- Coverage     74.46%   74.05%   -0.42%     
- Complexity    22234    23003     +769     
============================================
  Files          1963     2064     +101     
  Lines         82437    86224    +3787     
  Branches      10764    11332     +568     
============================================
+ Hits          61385    63851    +2466     
- Misses        15918    16938    +1020     
- Partials       5134     5435     +301

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2025-09-03T02:11:24Z

🔍 Build Scan® (commit: `e7a0237`)

Job name	Status	Build Scan®
build-ubicloud-standard-16-jdk-8	✅	https://ge.armeria.dev/s/wzx5bfcjhtajq
build-ubicloud-standard-16-jdk-21-snapshot-blockhound	✅	https://ge.armeria.dev/s/r7hmzttg2np4m
build-ubicloud-standard-16-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/swfn2q44rhrja
build-ubicloud-standard-16-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/43ll3igmksgeq
build-ubicloud-standard-16-jdk-17-leak	✅	https://ge.armeria.dev/s/xvrufdh7i622c
build-ubicloud-standard-16-jdk-11	❌ (failure)	https://ge.armeria.dev/s/bv4setesleku6
build-macos-latest-jdk-21	✅	https://ge.armeria.dev/s/iik5tzr7mksms

minwoox · 2025-09-03T02:52:24Z

...tated-service/src/main/java/example/armeria/server/animal/PolymorphismDocServiceExample.java

+        logger.info("JSON Specification: http://127.0.0.1:8080/docs/specification.json");
+    }
+
+    @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "species")


It seems like the subtypes are missing species, so deserialization actually doesn't work.
Also, this is not a tutorial, but just an example.
So, what do you think of making this class a test case (PolymorphismDocServiceTest) like we did for AnnotatedDocServiceTest?
We can use TestUtil.isDocServiceDemoMode() to see how it works on a browser.

Could you also use English for comments instead of Korean?

minwoox

Left a few more suggestions. 😎
Please, keep up the great work. 👍

core/src/main/java/com/linecorp/armeria/server/docs/DiscriminatorInfo.java

core/src/main/java/com/linecorp/armeria/server/docs/DocServiceTypeUtil.java

core/src/main/java/com/linecorp/armeria/server/docs/JacksonPolymorphismTypeInfoProvider.java

minwoox · 2025-09-03T05:21:26Z

core/src/main/java/com/linecorp/armeria/server/docs/JacksonPolymorphismTypeInfoProvider.java

+        }
+
+        final Map<String, String> mapping = new LinkedHashMap<>();
+        Arrays.stream(jsonSubTypes.value()).forEach(subType -> {


Should we also handle the case where jsonSubTypes.value() is empty?

Thank you for question regarding the empty subTypes case.

Here is a summary of my findings.

Test Setup

I created a misconfigured DTO specifically for this test:

// DTO with an intentionally empty @JsonSubTypes annotation @JsonTypeInfo(use = JsonTypeTypeInfo.Id.NAME, property = "type") @JsonSubTypes({}) interface MisconfiguredAnimal { String name(); }

1. Current Code

With the current implementation, when DocService processes MisconfiguredAnimal, it generates the following StructInfo in specification.json:

The oneOf field is missing. This is because the list is empty and the field is annotated with @JsonInclude(Include.NON_EMPTY).

The discriminator field is present, but its mapping is an empty object.

Resulting StructInfo snippet:

"name" : "...MisconfiguredAnimal", "fields" : [ ], "descriptionInfo" : { "docString" : "", "markup" : "NONE" }, "discriminator" : { "propertyName" : "type", "mapping" : { } }

This result seems inconsistent, as it describes a discriminator without any subtypes in oneOf.

2. After adding return null

After adding defensive check to JacksonPolymorphismTypeInfoProvider:

if (jsonSubTypes.value().length == 0) { return null; } final Map<String, String> mapping = new LinkedHashMap<>(); ...

The provider returns null for MisconfiguredAnimal. The request then falls back to DefaultDescriptiveTypeInfoProvider, which correctly treats it as a generic interface.

Resulting StructInfo snippet:

{ "name" : "...MisconfiguredAnimal", "fields" : [ ], "descriptionInfo" : { "docString" : "", "markup" : "NONE" } }

This result is clean and does not contain any misleading or incomplete polymorphism information.

Conclusion & Question

i think second one looks better, can i do this?

Thank you.

i think second one looks better, can i do this?

Yeah, that looks good. 👍

minwoox · 2025-09-03T06:50:11Z

core/src/main/java/com/linecorp/armeria/server/docs/JsonSchemaGenerator.java

+        if (structInfo != null) {
+            visited.put(firstParam.typeSignature(), "#");
+            generateProperties(structInfo.fields(), visited, "#", root);
+        }


Should we warn if structInfo == null?

core/src/main/java/com/linecorp/armeria/server/docs/JsonSchemaGenerator.java

minwoox · 2025-09-03T07:02:07Z

core/src/main/java/com/linecorp/armeria/server/docs/JsonSchemaGenerator.java

+                    fieldNode.set("additionalProperties", additionalPropertiesNode.get(""));
+                }
+                break;
+        }


What happends if the type is other types such as CONTAINER?

Adds a new `JacksonPolymorphismTypeInfoProvider` to generate correct JSON Schemas with `oneOf` and `discriminator` for polymorphic types annotated with `@JsonTypeInfo` and `@JsonSubTypes`.

YoungHoney marked this pull request as ready for review August 26, 2025 13:35

YoungHoney requested review from ikhoon, jrhee17, minwoox and trustin as code owners August 26, 2025 13:35

YoungHoney marked this pull request as draft August 26, 2025 13:35

YoungHoney force-pushed the YoungHoney6313 branch from 4e4ea3c to ac2b9e3 Compare September 1, 2025 12:28

YoungHoney marked this pull request as ready for review September 1, 2025 13:18

minwoox reviewed Sep 2, 2025

View reviewed changes

YoungHoney force-pushed the YoungHoney6313 branch from ac2b9e3 to e7a0237 Compare September 2, 2025 08:27

feat(docservice): Support Jackson polymorphism annotations(line#6370)

e7a0237

Adds a new `JacksonPolymorphismTypeInfoProvider` to generate correct JSON Schemas with `oneOf` and `discriminator` for polymorphic types annotated with `@JsonTypeInfo` and `@JsonSubTypes`.

minwoox reviewed Sep 3, 2025

View reviewed changes

feat(docservice): Support Jackson polymorphism annotations #6370

Are you sure you want to change the base?

feat(docservice): Support Jackson polymorphism annotations #6370

Uh oh!

Conversation

YoungHoney commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Modifications

Result

Example usage

Uh oh!

CLAassistant commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

minwoox commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Sep 3, 2025

🔍 Build Scan® (commit: e7a0237)

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

minwoox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

YoungHoney Sep 7, 2025

Choose a reason for hiding this comment

Test Setup

1. Current Code

2. After adding return null

Conclusion & Question

Uh oh!

minwoox Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

YoungHoney commented Aug 26, 2025 •

edited

Loading

CLAassistant commented Aug 26, 2025 •

edited

Loading

minwoox commented Aug 28, 2025 •

edited

Loading

codecov bot commented Sep 3, 2025 •

edited

Loading

🔍 Build Scan® (commit: `e7a0237`)

2. After adding `return null`