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 82.48588% with 62 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.11%. Comparing base (8150425) to head (4823d7b).
⚠️ Report is 182 commits behind head on main.

Files with missing lines	Patch %	Lines
...ecorp/armeria/server/docs/JsonSchemaGenerator.java	88.38%	11 Missing and 12 partials ⚠️
...a/com/linecorp/armeria/server/docs/StructInfo.java	42.30%	12 Missing and 3 partials ⚠️
...inecorp/armeria/server/docs/DiscriminatorInfo.java	43.75%	9 Missing ⚠️
...meria/internal/server/docs/DocServiceTypeUtil.java	89.47%	3 Missing and 5 partials ⚠️
...rver/docs/JacksonPolymorphismTypeInfoProvider.java	81.57%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #6370      +/-   ##
============================================
- Coverage     74.46%   74.11%   -0.35%     
- Complexity    22234    23016     +782     
============================================
  Files          1963     2063     +100     
  Lines         82437    86197    +3760     
  Branches      10764    11334     +570     
============================================
+ Hits          61385    63889    +2504     
- Misses        15918    16888     +970     
- Partials       5134     5420     +286

☔ 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: `4823d7b`)

Job name	Status	Build Scan®
build-ubicloud-standard-16-jdk-8	✅	https://ge.armeria.dev/s/kb755e4e3i5xo
build-ubicloud-standard-16-jdk-21-snapshot-blockhound	✅	https://ge.armeria.dev/s/acle5g72omtkc
build-ubicloud-standard-16-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/723afygldbouu
build-ubicloud-standard-16-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/tbrtholdfnwxa
build-ubicloud-standard-16-jdk-17-leak	✅	https://ge.armeria.dev/s/rz5uhki723wa6
build-ubicloud-standard-16-jdk-11	✅	https://ge.armeria.dev/s/xq2rhmqqfmvsw
build-macos-latest-jdk-21	✅	https://ge.armeria.dev/s/7obonbmdlib2a

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?

Thank you for the detailed and helpful feedback! I've addressed all of your suggestions based on our discussion.

Converted Example to a Test Case: As you suggested, the PolymorphismDocServiceExample.java has been removed entirely.

Created a Comprehensive Test Suite: I've added a new integration test, PolymorphismDocServiceTest.java. This new test suite now covers:

Correct documentation generation for polymorphic types (oneOf, discriminator).

deserialization of various polymorphic objects (Dog, Cat).

handling of edge cases, including misconfigured @JsonSubTypes({}) annotations and other types like Optional and Map.

I also confirmed that the TestUtil.isDocServiceDemoMode() works correctly for manual UI verification.

Used English for Comments: I've reviewed all new and modified files to ensure all comments are in English now.

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-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?

I've updated the code to handle the structInfo == null case as you suggested.

if (structInfo != null) { visited.put(firstParam.typeSignature(), "#"); generateProperties(structInfo.fields(), visited, "#", root); } else { logger.warn("Could not find root struct for signature: {}", firstParam.typeSignature().signature()); root.put("additionalProperties", true); }

Now, if a StructInfo for a gRPC request(may be) is not found:

A warning will be logged with the missing TypeSignature.

The generated schema for that method will fall back to using "additionalProperties": true, effectively treating it as a generic object.

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?

I've analyzed this and improved the generator's logic to handle these cases more robustly by “unwrapping” them to their inner types.

Implemented Solution

I've updated both getSchemaType and generateFieldSchema in JsonSchemaGenerator to recursively process OPTIONAL and CONTAINER types.

Code Snippet from JsonSchemaGenerator.java:

// In getSchemaType() case OPTIONAL: case CONTAINER: { // Unwrap and return the inner type's schema type final TypeSignature inner = ((ContainerTypeSignature) typeSignature).typeParameters().get(0); return getSchemaType(inner); } // In generateFieldSchema() if (typeSignature.type() == TypeSignatureType.OPTIONAL || typeSignature.type() == TypeSignatureType.CONTAINER) { final TypeSignature inner = ((ContainerTypeSignature) typeSignature).typeParameters().get(0); final ObjectNode innerNode = generateFieldSchema(FieldInfo.of("", inner)); fieldNode.setAll(innerNode); return fieldNode; }

Example and Results

To verify this, I've used the following service methods in the test code PolymorphismDocServiceTest :

// Container example static final class ApiResponse<T> { @JsonProperty private final int status; @JsonProperty private final T data; ApiResponse(int status, T data) { this.status = status; this.data = data; } } // OPTIONAL type in parameter @Post("/animal/optional") public String processOptionalAnimal(Optional<Animal> animal) { ... } // CONTAINER type in return value @Post("/dummy/api_response") public ApiResponse<Toy> getExampleResponse() { ... }

1. Result in specification.json:
The DocService correctly unwraps Optional<Animal> to its inner type Animal and marks it as OPTIONAL. For ApiResponse<Toy>, it correctly identifies the full generic type signature.

// For processOptionalAnimal { "id" : "...AnimalService/processOptionalAnimal/POST", "name" : "processOptionalAnimal", "returnTypeSignature" : "string", "parameters" : [ { "name" : "animal", "location" : "UNSPECIFIED", "requirement" : "OPTIONAL", "typeSignature" : "...$Animal", "descriptionInfo" : { "docString" : "", "markup" : "NONE" } } // For getExampleResponse { ... "returnTypeSignature": "ApiResponse<...PolymorphismDocServiceTest$Toy>" ... }

2. Result in schemas.json:

// part of Schema for processOptionalAnimal { "$id": ".../processOptionalAnimal/POST", "properties": { "animal": { "$ref": "#/definitions/...PolymorphismDocServiceTest$Animal" } } ... } //part of Schema for getExampleResponse { "$id" : ".../getExampleResponse/POST", "title" : "getExampleResponse", "additionalProperties" : false, "type" : "object", ... }

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

minwoox · 2025-09-19T07:38:27Z

I found a couple of issues in the generated JSON schema:

There are many duplicate definitions because each method has its own ID and definitions.

[
  {
    "$id": "...",
    "definitions": { ... } // duplicate definitions
  },
  {
    "$id": "...",
    "definitions": { ... } // duplicate definitions
  }
]

The "Cat" and "Dog" definitions are missing the species property, which is causing Autocomplete to fail.

To address this, I propose the following:

Use a root object with "$defs/methods" and "$defs/models" to put all methods and structs a single time.

It's worth noting that "definitions" is deprecated, as mentioned in the JSON Schema draft specification. https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#rfc.appendix.G

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "...",
  "title": "...",

  "$defs": {
    "methods": {
      "processAnimal": {
        "$id": "com.linecorp.armeria.server.docs.PolymorphismDocServiceTest$AnimalService/processAnimal/POST",
        "title": "processAnimal",
        "type": "object",
        "properties": {
          "animal": {
            "$ref": "#/$defs/models/Animal" 
          }
        },
        "required": [ "animal" ]
      },
      "processZoo": {
        ...
      }
    },

    "models": {
      "Animal": {
        "type": "object",
        "oneOf": [
          { "$ref": "#/$defs/models/Dog" },
          { "$ref": "#/$defs/models/Cat" }
        ],
        "discriminator": {
          "propertyName": "species",
          "mapping": {
            "dog": "#/$defs/models/Dog",
            "cat": "#/$defs/models/Cat"
          }
        }
      },
      "Cat": {
        "type": "object",
        "properties": {
          "species": { "type": "string" },
          "name": { "type": "string" },
          "likesTuna": { "type": "boolean" },
          "scratchPost": { "$ref": "#/$defs/models/Toy" },
          "vetRecord": { "$ref": "#/$defs/models/VetRecord" }
        },
        "required": [ "name", "likesTuna", "scratchPost", "vetRecord" ]
      },
      "Dog": {
        ...
      },
      ...
    }
  }
}

Update RequestBody.tsx to align with the new schema format. (I might help you if you are not familiar with the frontend)

Please, let me know your opinion. 🙇

YoungHoney · 2025-09-22T15:15:10Z

Use a root object with "$defs/methods" and "$defs/models" to put all methods and structs a single time.
* It's worth noting that "definitions" is deprecated, as mentioned in the JSON Schema draft specification

Thank you for your Review !

I've changed JsonSchemaGenerator based on your feedback, and I agree that the new structure is better than duplicated definitions . Here is the new output :

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "com.....$AnimalService",
  "title": "com....$AnimalService",
  "$defs": {
    "models": {
      "com....$Animal": {
        "type": "object",
        "title": "com....$Animal",
        "oneOf": [
          {
            "$ref": "#/$defs/models/com...$Dog"
          },
          {
            "$ref": "#/$defs/models/com.l...$Cat"
          }
        ],
        "discriminator": {
          "propertyName": "species",
          "mapping": {
            "dog": "#/$defs/models/com....$Dog",
            "cat": "#/$defs/models/com.....$Cat"
          }
        }
      },
      "com....$Cat": {
        "type": "object",
        "title": "com....$Cat",
        "properties": {
          "species": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "likesTuna": {
            "type": "boolean"
          },
          "scratchPost": {
            "$ref": "#/$defs/models/com....$Toy"
          },
          "vetRecord": {
            "$ref": "#/$defs/models/com....$VetRecord"
          }
        },
        "required": [ "name", "likesTuna", "scratchPost", "vetRecord", "species" ] // Should "species" be first? 
      },
      "...": "..."
    }, //models
    "methods": {
      "processAnimal": {
        "$id": "com....$AnimalService/processAnimal/POST",
        "title": "processAnimal",
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "animal": {
            "$ref": "#/$defs/models/com....$Animal"
          }
        },
        "required": [ "animal" ]
      },
      "...": "..."
    } //methods
  }
}

However, this change caused the existing GrpcDocServiceJsonSchemaTest to fail. This brings me to my main question:

Should I maintain backward compatibility for the gRPC schema, or should I update it to use the new, unified structure as well?

Also, as you mentioned, I'm not familiar with the frontend, so I would really appreciate your help with the RequestBody.tsx changes when the time comes.

minwoox · 2025-09-23T05:28:58Z

Should I maintain backward compatibility for the gRPC schema, or should I update it to use the new, unified structure as well?

I think we don't have to worry about the compatibility because the browser will fetch the new JSON schema and use it for the autocompletion.

Also, as you mentioned, I'm not familiar with the frontend, so I would really appreciate your help with the RequestBody.tsx changes when the time comes.

I'm happy to help you. 😉 Will push a commit after the server-side changes are done.

0929-2

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

minwoox reviewed Sep 3, 2025

View reviewed changes

YoungHoney added a commit to YoungHoney/armeria that referenced this pull request Sep 12, 2025

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

4823d7b

YoungHoney force-pushed the YoungHoney6313 branch from e7a0237 to 4823d7b Compare September 12, 2025 15:40

minwoox added the improvement label Sep 19, 2025

minwoox added this to the 1.34.0 milestone Sep 19, 2025

YoungHoney added a commit to YoungHoney/armeria that referenced this pull request Sep 28, 2025

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

e02df82

YoungHoney force-pushed the YoungHoney6313 branch from 4823d7b to e02df82 Compare September 28, 2025 15:30

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

6017c7d

0929-2

YoungHoney force-pushed the YoungHoney6313 branch from e02df82 to 6017c7d Compare September 28, 2025 15:34

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Build Scan® (commit: 4823d7b)

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

YoungHoney Sep 12, 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!

Uh oh!

minwoox Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

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!

YoungHoney Sep 12, 2025

Choose a reason for hiding this comment

Implemented Solution

Example and Results

Uh oh!

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

Uh oh!

Uh oh!

YoungHoney commented Sep 22, 2025

Uh oh!

minwoox commented Sep 23, 2025

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

github-actions bot commented Sep 3, 2025 •

edited

Loading

🔍 Build Scan® (commit: `4823d7b`)

YoungHoney Sep 12, 2025 •

edited

Loading

minwoox commented Sep 19, 2025 •

edited

Loading