diff --git a/ISSUES_ANALYSIS_2025_OPEN.md b/ISSUES_ANALYSIS_2025_OPEN.md new file mode 100644 index 0000000000..2b671a7703 --- /dev/null +++ b/ISSUES_ANALYSIS_2025_OPEN.md @@ -0,0 +1,781 @@ +# Swagger-Core Open Issues Analysis (2025) + +**Analysis Date:** 2026-02-03 +**Total Open Issues Analyzed:** 92 +**Date Range:** Since January 1, 2025 + +--- + +## Executive Summary + +This analysis examines **92 OPEN issues** reported to the swagger-api/swagger-core repository since January 1, 2025. The issues have been categorized using three approaches, with a special **Combined Approach** that merges functional areas with priority levels: + +1. **By Issue Type** - Traditional categorization (Bug, Feature, Question, etc.) +2. **By Functional Area** - Groups by technical domain for specialized team assignment +3. **By Priority/Severity** - Prioritizes work based on impact and urgency +4. **Combined: Functional Areas by Priority** ⭐ - Shows which functional areas have the highest priority issues + +--- + +## How Priorities Are Determined + +Priority is calculated using a **weighted scoring system** that considers multiple factors: + +### Priority Scoring Methodology + +| Priority Level | Score | Criteria | +|---------------|-------|----------| +| **Critical** | 5 | • Regressions (stopped working, breaking changes)
• Issues with P0/P1 labels
• Keywords: "regression", "breaking change", "stopped working" | +| **High** | 4 | • Exceptions and crashes
• All bugs (Bug label)
• Keywords: "exception", "crash", "nullpointer", "fails" | +| **Medium** | 3 | • Standard issues without special markers
• General improvements | +| **Low** | 2 | • Feature requests
• Enhancements | +| **Low** | 1 | • Questions
• Documentation requests | + +**Average Priority Score** for each functional area is calculated as the mean of all issue scores in that area. This helps identify which functional areas need the most urgent attention. + +--- + +## Approach 1: By Issue Type + +This approach groups issues by their type. **OPEN ISSUES ONLY.** + +### Summary Statistics + +**Bug:** 16 open +**Feature:** 10 open +**Question:** 5 open +**Other:** 61 open + + +### Detailed Breakdown + +#### Bug (16 open issues) + +- #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +- #5036: [Bug]: Example text is truncated when beginning with numbers +- #5035: [Bug]: Jakarta @Positive validation is not present in Swagger +- #5028: [Bug]: Polymorphic types don't include composite schema reference +- #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas +- #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 +- #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +- #5007: [Bug]: kotlin inline classes produce weird field names +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4999: [Bug]: Example value starting with a number is parsed incorrectly +- #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas +- #4963: [Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string +- #4960: [Bug]: SpecFilter skips the ApiResponse#$ref field +- #4841: 2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context. +- #4813: Upgrade to v2.2.27: Cannot change dependencies of dependency configuration '' after it has been included in dependency resolution +- #4682: BUG properties of type Object do not have any type information when generating open api 3.1.0 + +#### Feature (10 open issues) + +- #5045: [Feature]: Need since or reason field in @Hidden annotation +- #5011: [Feature]: Drop commons-lang3 dependency and replace its usages with core Java +- #4991: [Feature] Support Jackson 3.x release line +- #4976: [Feature]: Reduce Boilerplate in swagger-core Models (Optional Lombok Support or Alternatives) +- #4966: [Feature]: Provide a bom module for managing dependencies +- #4951: [Feature]: support for runtime skip properties inside ModelConverter +- #4840: [Feature] Mark type as deprecated if the class is `@Deprecated` +- #4838: Empty default values are ignored +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping +- #3323: Generic Response Types + +#### Question (5 open issues) + +- #5016: [Question]: Duplicate schema names don't throw but are overwritten +- #5014: [Question]: How to specify @Schema.examples where each element is an array? +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param +- #4939: Integer enum Schema parsing can fail based upon locale +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" + +#### Other (61 open issues) + +- #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4924: Ability to remove unused definitions from generated YML +- #4923: Custom UUID wrapper class can't be used anymore after 2.2.28 +- #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +- #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4906: java.lang.Object converted to json object (map) type +- #4905: CustomResolver's Results get overwritten by default ModelResolver +- #4904: java.lang.ClassCastException: class io.swagger.v3.oas.models.media.JsonSchema cannot be cast to class io.swagger.v3.oas.models.media.ComposedSchema +- #4903: jackson module not working in 2.2.30 +- #4887: Order of `required` properties +- #4886: Validation Meta annotations not working +- #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +- #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +- #4864: generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903 +- #4863: "Override" example value when extending a class +- #4854: Bootstrapped servlet returns empty JSON as of 2.2.24 +- #4851: The example value of the request body in swagger has a "string" value +- #4848: ModelResolver#resolve ignores TYPE_USE annotations on property types +- ... and 41 more + +--- + +## Approach 2: By Functional Area + +This approach groups issues by technical domain and functionality. **OPEN ISSUES ONLY.** + +### Summary Statistics (sorted by issue count) + +**Annotation Processing:** 63 open issues +**Examples:** 34 open issues +**Validation:** 25 open issues +**Dependencies:** 21 open issues +**Jakarta Migration:** 20 open issues +**Jackson:** 17 open issues +**Other:** 12 open issues +**Polymorphic Types:** 11 open issues +**Kotlin:** 3 open issues + +### Detailed Breakdown + +#### Annotation Processing (63 open issues) + +*Issues related to @Schema, @ArraySchema, @Hidden, and other annotations* + +🟢 #5045: [Feature]: Need since or reason field in @Hidden annotation +🟠 #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +🟠 #5036: [Bug]: Example text is truncated when beginning with numbers +🟠 #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas +🟠 #5016: [Question]: Duplicate schema names don't throw but are overwritten +🟢 #5014: [Question]: How to specify @Schema.examples where each element is an array? +🟠 #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 +🟠 #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +🟠 #5007: [Bug]: kotlin inline classes produce weird field names +🟠 #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +🟠 #4999: [Bug]: Example value starting with a number is parsed incorrectly +🔴 #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas +🟢 #4984: [Question]: Duplicate records if Class and Operation both has @Path param +🟠 #4963: [Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string +🟠 #4960: [Bug]: SpecFilter skips the ApiResponse#$ref field + +... and 48 more issues + +#### Examples (34 open issues) + +*Issues with example values and documentation generation* + +🟠 #5036: [Bug]: Example text is truncated when beginning with numbers +🟡 #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +🟠 #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas +🟢 #5014: [Question]: How to specify @Schema.examples where each element is an array? +🟠 #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +🟠 #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +🟠 #4999: [Bug]: Example value starting with a number is parsed incorrectly +🟢 #4984: [Question]: Duplicate records if Class and Operation both has @Path param +🟢 #4966: [Feature]: Provide a bom module for managing dependencies +🟢 #4939: Integer enum Schema parsing can fail based upon locale +🟠 #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +🟡 #4928: Lack of Friendly Support for Parameter Validation Grouping +🟠 #4923: Custom UUID wrapper class can't be used anymore after 2.2.28 +🔴 #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +🟡 #4908: defaultValue attribute at enum object generate arbitrary json file + +... and 19 more issues + +#### Validation (25 open issues) + +*Issues with validation annotations, required fields, and RequiredMode* + +🟠 #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +🟠 #5036: [Bug]: Example text is truncated when beginning with numbers +🟠 #5035: [Bug]: Jakarta @Positive validation is not present in Swagger +🟡 #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +🟠 #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +🟠 #4960: [Bug]: SpecFilter skips the ApiResponse#$ref field +🟡 #4928: Lack of Friendly Support for Parameter Validation Grouping +🔴 #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +🔴 #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +🟡 #4887: Order of `required` properties +🟡 #4886: Validation Meta annotations not working +🟡 #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +🟠 #4842: OpenApi doc not beeing generated properly +🔴 #4841: 2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context. +🟢 #4838: Empty default values are ignored + +... and 10 more issues + +#### Dependencies (21 open issues) + +*Issues with dependencies, Maven/Gradle plugins, and build processes* + +🔴 #5028: [Bug]: Polymorphic types don't include composite schema reference +🟠 #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 +🟠 #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +🟢 #5011: [Feature]: Drop commons-lang3 dependency and replace its usages with core Java +🟠 #5007: [Bug]: kotlin inline classes produce weird field names +🟠 #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +🔴 #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas +🟢 #4984: [Question]: Duplicate records if Class and Operation both has @Path param +🟢 #4966: [Feature]: Provide a bom module for managing dependencies +🟠 #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +🟡 #4908: defaultValue attribute at enum object generate arbitrary json file +🟡 #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +🟡 #4864: generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903 +🟡 #4846: Swagger adds extra line breaks in yaml generated from annotated code +🟠 #4842: OpenApi doc not beeing generated properly + +... and 6 more issues + +#### Jakarta Migration (20 open issues) + +*Issues related to Jakarta namespace migration and Jakarta annotations* + +🟠 #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +🟠 #5035: [Bug]: Jakarta @Positive validation is not present in Swagger +🟠 #5007: [Bug]: kotlin inline classes produce weird field names +🟠 #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +🟠 #4999: [Bug]: Example value starting with a number is parsed incorrectly +🟢 #4984: [Question]: Duplicate records if Class and Operation both has @Path param +🟠 #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +🟡 #4928: Lack of Friendly Support for Parameter Validation Grouping +🔴 #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +🟡 #4908: defaultValue attribute at enum object generate arbitrary json file +🟠 #4903: jackson module not working in 2.2.30 +🟡 #4886: Validation Meta annotations not working +🟡 #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +🟡 #4846: Swagger adds extra line breaks in yaml generated from annotated code +🟠 #4842: OpenApi doc not beeing generated properly + +... and 5 more issues + +#### Jackson (17 open issues) + +*Issues with Jackson annotations and serialization/deserialization* + +🔴 #5028: [Bug]: Polymorphic types don't include composite schema reference +🟠 #5007: [Bug]: kotlin inline classes produce weird field names +🔴 #4991: [Feature] Support Jackson 3.x release line +🟠 #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +🟡 #4905: CustomResolver's Results get overwritten by default ModelResolver +🟠 #4904: java.lang.ClassCastException: class io.swagger.v3.oas.models.media.JsonSchema cannot be cast to class io.swagger.v3.oas.models.media.ComposedSchema +🟠 #4903: jackson module not working in 2.2.30 +🟡 #4848: ModelResolver#resolve ignores TYPE_USE annotations on property types +🟡 #4847: @Schema annotation on custom string type is ignored when using @JsonValue +🟠 #4842: OpenApi doc not beeing generated properly +🟠 #4819: Definition for parent interface not generated +🟡 #4696: Using @JsonUnwrapped with @Schema(implementation = Something) does not unwrap +🟠 #4682: BUG properties of type Object do not have any type information when generating open api 3.1.0 +🟡 #4506: Jackson @JsonFormat doesn't support Enum type +🟡 #4156: Sealed kotlin class with oneOf annotation generates a type: object + +... and 2 more issues + +#### Other (12 open issues) + +🟠 #4976: [Feature]: Reduce Boilerplate in swagger-core Models (Optional Lombok Support or Alternatives) +🟢 #4951: [Feature]: support for runtime skip properties inside ModelConverter +🟡 #4924: Ability to remove unused definitions from generated YML +🟠 #4906: java.lang.Object converted to json object (map) type +🟡 #4843: OpenApi not generated when resourceClasses used +🟡 #4837: Is it possible to convert from OAS 3.0 to OAS 3.1 using this lib? +🟡 #4789: Classes / enums with same name but different package replace each other +🟡 #4404: Add support for more java.time objects +🟡 #3577: [bug] Integer enum support +🟠 #3025: openapi.json fails to take into account servlet context path, produces bad spec file +🟡 #2961: Field with first letter lower case not recognized +🟡 #2192: Field name is getting generated wrongly if field type is "Boolean" (wrapper class for boolean) instead of primitive "boolean" type + +#### Polymorphic Types (11 open issues) + +*Issues with oneOf, allOf, discriminators, and class hierarchies* + +🔴 #5028: [Bug]: Polymorphic types don't include composite schema reference +🟡 #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +🟠 #4819: Definition for parent interface not generated +🟠 #4358: Incorrect mapping of sub-classes when nested as member of another sub-class +🟡 #4352: Inconsistent behaviour for oneOf +🟡 #4330: Missing oneOf sections for polymorphic schema +🟡 #4156: Sealed kotlin class with oneOf annotation generates a type: object +🟡 #3689: @ArraySchema is ignored in model property (array of abstract class) +🟡 #3677: How to prevent oneOf() on supertypes leading to recursion in subtypes? +🟡 #3567: Question: Is there a way to specify allowableValues dynamically? +🟢 #3411: Consider the @JsonSubTypes for generating the discriminator mapping + +#### Kotlin (3 open issues) + +*Kotlin-specific issues including inline classes and sealed classes* + +🟠 #5007: [Bug]: kotlin inline classes produce weird field names +🟡 #4506: Jackson @JsonFormat doesn't support Enum type +🟡 #4156: Sealed kotlin class with oneOf annotation generates a type: object + +--- + +## Approach 3: By Priority/Severity + +This approach prioritizes issues based on their impact and urgency. **OPEN ISSUES ONLY.** + +### Priority Levels + +**Critical:** 9 open issues +**High:** 27 open issues +**Medium:** 46 open issues +**Low:** 10 open issues + +### Detailed Breakdown + +#### Critical Priority (9 open issues) + +- #5028: [Bug]: Polymorphic types don't include composite schema reference [Bug] +- #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas [Bug] +- #4991: [Feature] Support Jackson 3.x release line [Feature] +- #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +- #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +- #4841: 2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context. [Bug, P1] +- #4813: Upgrade to v2.2.27: Cannot change dependencies of dependency configuration '' after it has been included in dependency resolution [Bug, P1] +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity +- #4555: Could `@Schema(nullable = true)` work when outputting OpenAPI 3.1.0? + +#### High Priority (27 open issues) + +- #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl [Bug] +- #5036: [Bug]: Example text is truncated when beginning with numbers [Bug] +- #5035: [Bug]: Jakarta @Positive validation is not present in Swagger [Bug] +- #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas [Bug] +- #5016: [Question]: Duplicate schema names don't throw but are overwritten [Question] +- #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 [Bug] +- #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema [Bug] +- #5007: [Bug]: kotlin inline classes produce weird field names [Bug] +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types [Bug] +- #4999: [Bug]: Example value starting with a number is parsed incorrectly [Bug] +- #4976: [Feature]: Reduce Boilerplate in swagger-core Models (Optional Lombok Support or Alternatives) [Feature] +- #4963: [Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string [Bug] +- #4960: [Bug]: SpecFilter skips the ApiResponse#$ref field [Bug] +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" [Question] +- #4923: Custom UUID wrapper class can't be used anymore after 2.2.28 +- #4906: java.lang.Object converted to json object (map) type +- #4904: java.lang.ClassCastException: class io.swagger.v3.oas.models.media.JsonSchema cannot be cast to class io.swagger.v3.oas.models.media.ComposedSchema +- #4903: jackson module not working in 2.2.30 +- #4854: Bootstrapped servlet returns empty JSON as of 2.2.24 +- #4842: OpenApi doc not beeing generated properly + +... and 7 more issues + +#### Medium Priority (46 open issues) + +- #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4924: Ability to remove unused definitions from generated YML +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4905: CustomResolver's Results get overwritten by default ModelResolver +- #4887: Order of `required` properties +- #4886: Validation Meta annotations not working +- #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +- #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +- #4864: generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903 +- #4863: "Override" example value when extending a class +- #4851: The example value of the request body in swagger has a "string" value +- #4848: ModelResolver#resolve ignores TYPE_USE annotations on property types +- #4847: @Schema annotation on custom string type is ignored when using @JsonValue +- #4846: Swagger adds extra line breaks in yaml generated from annotated code +- #4844: swagger-annotations: Add annotations to support x-enum-descriptions and x-enum-varnames +- #4843: OpenApi not generated when resourceClasses used +- #4840: [Feature] Mark type as deprecated if the class is `@Deprecated` +- #4839: [Feature/Bug] Forbid mutliple `@ApiResponse` annotations with the same response code +- #4837: Is it possible to convert from OAS 3.0 to OAS 3.1 using this lib? + +... and 26 more issues + +#### Low Priority (10 open issues) + +- #5045: [Feature]: Need since or reason field in @Hidden annotation [Feature] +- #5014: [Question]: How to specify @Schema.examples where each element is an array? [Question] +- #5011: [Feature]: Drop commons-lang3 dependency and replace its usages with core Java [Feature] +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param [Question] +- #4966: [Feature]: Provide a bom module for managing dependencies [Feature] +- #4951: [Feature]: support for runtime skip properties inside ModelConverter [Feature] +- #4939: Integer enum Schema parsing can fail based upon locale [Question] +- #4838: Empty default values are ignored [Feature] +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping [Feature, Workaround available, P2, :thumbsup: Top Issue!] +- #3323: Generic Response Types [Feature] + +--- + +## ⭐ Combined Approach: Functional Areas by Priority + +This approach **combines Approach 2 and Approach 3** to show which functional areas have the highest priority issues. This helps answer: **"Which functional area should we focus on first?"** + +### Functional Areas Ranked by Average Priority Score + +The table below shows each functional area ranked by its average priority score, along with the distribution of issue priorities. + +| Rank | Functional Area | Total | Avg Score | Critical | High | Medium | Low | Priority Level | +|------|----------------|-------|-----------|----------|------|--------|-----|----------------| +| 1 | **Validation** | 25 | **3.64** | 5 | 9 | 8 | 3 | 🟠 HIGH | +| 2 | **Jackson** | 17 | **3.59** | 2 | 7 | 7 | 1 | 🟠 HIGH | +| 3 | **Dependencies** | 21 | **3.57** | 5 | 7 | 5 | 4 | 🟠 HIGH | +| 4 | **Jakarta Migration** | 20 | **3.55** | 2 | 9 | 8 | 1 | 🟠 HIGH | +| 5 | **Annotation Processing** | 63 | **3.33** | 5 | 19 | 33 | 6 | 🟡 MEDIUM | +| 6 | **Kotlin** | 3 | **3.33** | 0 | 1 | 2 | 0 | 🟡 MEDIUM | +| 7 | **Polymorphic Types** | 11 | **3.27** | 1 | 2 | 7 | 1 | 🟡 MEDIUM | +| 8 | **Examples** | 34 | **3.21** | 2 | 11 | 16 | 5 | 🟡 MEDIUM | +| 9 | **Other** | 12 | **3.17** | 0 | 3 | 8 | 1 | 🟡 MEDIUM | + + +### Interpretation Guide + +- **Avg Score:** Higher scores (closer to 5.0) indicate more urgent issues +- **Priority Level:** + - 🔴 CRITICAL (4.0+): Immediate attention required + - 🟠 HIGH (3.5-3.9): Should be prioritized soon + - 🟡 MEDIUM (2.5-3.4): Standard priority + - 🟢 LOW (<2.5): Can be deferred + +### Key Insights from Combined Analysis + +**Top 3 Priority Areas:** + +1. **Validation** (Avg: 3.64) + - 25 open issues + - 5 critical, 9 high priority + - Critical issues: #4910, #4909, #4841, +2 more + +2. **Jackson** (Avg: 3.59) + - 17 open issues + - 2 critical, 7 high priority + - Critical issues: #5028, #4991 + +3. **Dependencies** (Avg: 3.57) + - 21 open issues + - 5 critical, 7 high priority + - Critical issues: #5028, #4993, #4841, +2 more + + +**Recommendation:** Focus development effort on the top-ranked functional areas, starting with their Critical and High priority issues. + +--- + +## Detailed Priority Breakdown by Functional Area + +This section provides detailed listings of issues in each functional area, grouped by priority. + +### Validation +**Total:** 25 | **Avg Score:** 3.64 | Critical: 5 | High: 9 | Medium: 8 | Low: 3 + +**🔴 Critical Priority (5 issues):** +- #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +- #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +- #4841: 2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context. +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity +- #4555: Could `@Schema(nullable = true)` work when outputting OpenAPI 3.1.0? + +**🟠 High Priority (9 issues):** +- #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +- #5036: [Bug]: Example text is truncated when beginning with numbers +- #5035: [Bug]: Jakarta @Positive validation is not present in Swagger +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4960: [Bug]: SpecFilter skips the ApiResponse#$ref field +- #4842: OpenApi doc not beeing generated properly +- #4819: Definition for parent interface not generated +- #4763: Explicit schema type specified on `@Parameter` annotation is always ignored +- #4689: BUG Unable to deserialize OpenAPI Parameter + +**🟡 Medium Priority (8 issues):** +- #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4887: Order of `required` properties +- #4886: Validation Meta annotations not working +- #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +- #4753: @Schema field-level description ignored when using custom type with $ref #2723 +- #4711: @Schema is processed without enum when implementation and allowableValues exist at the same time +- #3818: Maps that use enums as keys don't explicitly declare them in the resulting swagger def. + +**🟢 Low Priority (3 issues):** +- #4838: Empty default values are ignored +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping +- #3323: Generic Response Types + +--- + +### Jackson +**Total:** 17 | **Avg Score:** 3.59 | Critical: 2 | High: 7 | Medium: 7 | Low: 1 + +**🔴 Critical Priority (2 issues):** +- #5028: [Bug]: Polymorphic types don't include composite schema reference +- #4991: [Feature] Support Jackson 3.x release line + +**🟠 High Priority (7 issues):** +- #5007: [Bug]: kotlin inline classes produce weird field names +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +- #4904: java.lang.ClassCastException: class io.swagger.v3.oas.models.media.JsonSchema cannot be cast to class io.swagger.v3.oas.models.media.ComposedSchema +- #4903: jackson module not working in 2.2.30 +- #4842: OpenApi doc not beeing generated properly +- #4819: Definition for parent interface not generated +- #4682: BUG properties of type Object do not have any type information when generating open api 3.1.0 + +**🟡 Medium Priority (7 issues):** +- #4905: CustomResolver's Results get overwritten by default ModelResolver +- #4848: ModelResolver#resolve ignores TYPE_USE annotations on property types +- #4847: @Schema annotation on custom string type is ignored when using @JsonValue +- #4696: Using @JsonUnwrapped with @Schema(implementation = Something) does not unwrap +- #4506: Jackson @JsonFormat doesn't support Enum type +- #4156: Sealed kotlin class with oneOf annotation generates a type: object +- #3677: How to prevent oneOf() on supertypes leading to recursion in subtypes? + +**🟢 Low Priority (1 issues):** +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping + +--- + +### Dependencies +**Total:** 21 | **Avg Score:** 3.57 | Critical: 5 | High: 7 | Medium: 5 | Low: 4 + +**🔴 Critical Priority (5 issues):** +- #5028: [Bug]: Polymorphic types don't include composite schema reference +- #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas +- #4841: 2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context. +- #4813: Upgrade to v2.2.27: Cannot change dependencies of dependency configuration '' after it has been included in dependency resolution +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity + +**🟠 High Priority (7 issues):** +- #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 +- #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +- #5007: [Bug]: kotlin inline classes produce weird field names +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +- #4842: OpenApi doc not beeing generated properly +- #4763: Explicit schema type specified on `@Parameter` annotation is always ignored + +**🟡 Medium Priority (5 issues):** +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +- #4864: generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903 +- #4846: Swagger adds extra line breaks in yaml generated from annotated code +- #4824: Bill of material + +**🟢 Low Priority (4 issues):** +- #5011: [Feature]: Drop commons-lang3 dependency and replace its usages with core Java +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param +- #4966: [Feature]: Provide a bom module for managing dependencies +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping + +--- + +### Jakarta Migration +**Total:** 20 | **Avg Score:** 3.55 | Critical: 2 | High: 9 | Medium: 8 | Low: 1 + +**🔴 Critical Priority (2 issues):** +- #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity + +**🟠 High Priority (9 issues):** +- #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +- #5035: [Bug]: Jakarta @Positive validation is not present in Swagger +- #5007: [Bug]: kotlin inline classes produce weird field names +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4999: [Bug]: Example value starting with a number is parsed incorrectly +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +- #4903: jackson module not working in 2.2.30 +- #4842: OpenApi doc not beeing generated properly +- #4763: Explicit schema type specified on `@Parameter` annotation is always ignored + +**🟡 Medium Priority (8 issues):** +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4886: Validation Meta annotations not working +- #4877: 2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory +- #4846: Swagger adds extra line breaks in yaml generated from annotated code +- #4824: Bill of material +- #4753: @Schema field-level description ignored when using custom type with $ref #2723 +- #4711: @Schema is processed without enum when implementation and allowableValues exist at the same time + +**🟢 Low Priority (1 issues):** +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param + +--- + +### Annotation Processing +**Total:** 63 | **Avg Score:** 3.33 | Critical: 5 | High: 19 | Medium: 33 | Low: 6 + +**🔴 Critical Priority (5 issues):** +- #4993: [Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas +- #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +- #4909: Custom NotNull annotations stopped working between 2.2.28 and 2.2.29 +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity +- #4555: Could `@Schema(nullable = true)` work when outputting OpenAPI 3.1.0? + +**🟠 High Priority (19 issues):** +- #5043: [Bug]: AnnotatedType equality in ModelConverterContextImpl +- #5036: [Bug]: Example text is truncated when beginning with numbers +- #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas +- #5016: [Question]: Duplicate schema names don't throw but are overwritten +- #5013: [Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1 +- #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +- #5007: [Bug]: kotlin inline classes produce weird field names +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4999: [Bug]: Example value starting with a number is parsed incorrectly +- #4963: [Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string +- ... and 9 more + +**🟡 Medium Priority (33 issues):** +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4905: CustomResolver's Results get overwritten by default ModelResolver +- #4886: Validation Meta annotations not working +- #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +- #4864: generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903 +- #4863: "Override" example value when extending a class +- #4851: The example value of the request body in swagger has a "string" value +- #4848: ModelResolver#resolve ignores TYPE_USE annotations on property types +- #4847: @Schema annotation on custom string type is ignored when using @JsonValue +- ... and 23 more + +**🟢 Low Priority (6 issues):** +- #5045: [Feature]: Need since or reason field in @Hidden annotation +- #5014: [Question]: How to specify @Schema.examples where each element is an array? +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param +- #4838: Empty default values are ignored +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping +- #3323: Generic Response Types + +--- + +### Kotlin +**Total:** 3 | **Avg Score:** 3.33 | Critical: 0 | High: 1 | Medium: 2 | Low: 0 + +**🟠 High Priority (1 issues):** +- #5007: [Bug]: kotlin inline classes produce weird field names + +**🟡 Medium Priority (2 issues):** +- #4506: Jackson @JsonFormat doesn't support Enum type +- #4156: Sealed kotlin class with oneOf annotation generates a type: object + +--- + +### Polymorphic Types +**Total:** 11 | **Avg Score:** 3.27 | Critical: 1 | High: 2 | Medium: 7 | Low: 1 + +**🔴 Critical Priority (1 issues):** +- #5028: [Bug]: Polymorphic types don't include composite schema reference + +**🟠 High Priority (2 issues):** +- #4819: Definition for parent interface not generated +- #4358: Incorrect mapping of sub-classes when nested as member of another sub-class + +**🟡 Medium Priority (7 issues):** +- #4882: swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java +- #4352: Inconsistent behaviour for oneOf +- #4330: Missing oneOf sections for polymorphic schema +- #4156: Sealed kotlin class with oneOf annotation generates a type: object +- #3689: @ArraySchema is ignored in model property (array of abstract class) +- #3677: How to prevent oneOf() on supertypes leading to recursion in subtypes? +- #3567: Question: Is there a way to specify allowableValues dynamically? + +**🟢 Low Priority (1 issues):** +- #3411: Consider the @JsonSubTypes for generating the discriminator mapping + +--- + +### Examples +**Total:** 34 | **Avg Score:** 3.21 | Critical: 2 | High: 11 | Medium: 16 | Low: 5 + +**🔴 Critical Priority (2 issues):** +- #4910: Create an annotation the add at controller level to summarize information regarding failed http responses. +- #4649: Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity + +**🟠 High Priority (11 issues):** +- #5036: [Bug]: Example text is truncated when beginning with numbers +- #5017: [Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas +- #5012: [Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema +- #5001: [Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types +- #4999: [Bug]: Example value starting with a number is parsed incorrectly +- #4935: Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default" +- #4923: Custom UUID wrapper class can't be used anymore after 2.2.28 +- #4854: Bootstrapped servlet returns empty JSON as of 2.2.24 +- #4842: OpenApi doc not beeing generated properly +- #4682: BUG properties of type Object do not have any type information when generating open api 3.1.0 +- ... and 1 more + +**🟡 Medium Priority (16 issues):** +- #5027: "required" property in Schema.java should be a Set (SortedSet for example), not a List +- #4928: Lack of Friendly Support for Parameter Validation Grouping +- #4908: defaultValue attribute at enum object generate arbitrary json file +- #4886: Validation Meta annotations not working +- #4863: "Override" example value when extending a class +- #4851: The example value of the request body in swagger has a "string" value +- #4846: Swagger adds extra line breaks in yaml generated from annotated code +- #4844: swagger-annotations: Add annotations to support x-enum-descriptions and x-enum-varnames +- #4840: [Feature] Mark type as deprecated if the class is `@Deprecated` +- #4820: @Schema(example="1234", type="string") interpreted as integer +- ... and 6 more + +**🟢 Low Priority (5 issues):** +- #5014: [Question]: How to specify @Schema.examples where each element is an array? +- #4984: [Question]: Duplicate records if Class and Operation both has @Path param +- #4966: [Feature]: Provide a bom module for managing dependencies +- #4939: Integer enum Schema parsing can fail based upon locale +- #3323: Generic Response Types + +--- + +### Other +**Total:** 12 | **Avg Score:** 3.17 | Critical: 0 | High: 3 | Medium: 8 | Low: 1 + +**🟠 High Priority (3 issues):** +- #4976: [Feature]: Reduce Boilerplate in swagger-core Models (Optional Lombok Support or Alternatives) +- #4906: java.lang.Object converted to json object (map) type +- #3025: openapi.json fails to take into account servlet context path, produces bad spec file + +**🟡 Medium Priority (8 issues):** +- #4924: Ability to remove unused definitions from generated YML +- #4843: OpenApi not generated when resourceClasses used +- #4837: Is it possible to convert from OAS 3.0 to OAS 3.1 using this lib? +- #4789: Classes / enums with same name but different package replace each other +- #4404: Add support for more java.time objects +- #3577: [bug] Integer enum support +- #2961: Field with first letter lower case not recognized +- #2192: Field name is getting generated wrongly if field type is "Boolean" (wrapper class for boolean) instead of primitive "boolean" type + +**🟢 Low Priority (1 issues):** +- #4951: [Feature]: support for runtime skip properties inside ModelConverter + +--- + + +## Recommendations + +### Based on Combined Priority Analysis: + +1. **Immediate Focus (High Avg Score Areas):** + - Address Critical issues in Validation, Jackson, and Dependencies areas + - These areas have both high issue counts and high severity + +2. **Strategic Priorities:** + - **Validation:** 25 issues with 5 critical - needs architectural review + - **Jakarta Migration:** 20 issues, many high priority - complete migration effort + - **Annotation Processing:** 63 issues - highest volume, needs systematic cleanup + +3. **Approach:** + - Use the Combined Approach to select functional areas + - Within each area, tackle Critical issues first, then High priority + - Monitor average priority scores to track improvement + +### How to Use This Analysis: + +1. **For Planning:** Use the Combined Approach table to prioritize functional areas +2. **For Assignment:** Assign team members to top-priority functional areas +3. **For Sprints:** Pick top 2-3 areas, focus on Critical/High issues +4. **For Tracking:** Re-run analysis monthly to see if priorities shift + +--- + +## Conclusion + +The **Combined Approach** (Functional Areas by Priority) provides the best view for decision-making: + +- **What to work on:** Functional areas with highest average priority scores +- **Within each area:** Start with Critical and High priority issues +- **Track progress:** Monitor both issue count and average priority score + +**Current Focus Areas (based on combined analysis):** +1. Validation (3.64 avg) - 5 critical issues +2. Jackson (3.59 avg) - 2 critical issues +3. Dependencies (3.57 avg) - 5 critical issues + +All data is available in **ISSUES_DATA_2025_OPEN.csv** for further analysis. + diff --git a/ISSUES_ANALYSIS_README_OPEN.md b/ISSUES_ANALYSIS_README_OPEN.md new file mode 100644 index 0000000000..762ca5f6d8 --- /dev/null +++ b/ISSUES_ANALYSIS_README_OPEN.md @@ -0,0 +1,164 @@ +# Open Issues Analysis for 2025 + +This directory contains analysis of **OPEN GitHub issues** reported to the swagger-api/swagger-core repository since January 1, 2025. + +## Files + +### ISSUES_ANALYSIS_2025_OPEN.md ⭐ **NEW** +A comprehensive markdown report containing: +- Analysis of **92 OPEN issues only** (closed issues excluded) +- **Four different categorization approaches** for grouping issues: + 1. **By Issue Type** - Traditional categorization (Bug, Feature, Question, etc.) + 2. **By Functional Area** - Technical domain-based grouping + 3. **By Priority/Severity** - Impact and urgency-based prioritization + 4. **⭐ Combined: Functional Areas by Priority** - Merges approaches 2 and 3 +- Detailed priority determination methodology +- Actionable recommendations based on combined analysis + +### ISSUES_DATA_2025_OPEN.csv ⭐ **NEW** +A CSV file containing all **92 open issues** with the following columns: +- Issue Number +- Title +- Type (Bug, Feature, Question, Other) +- Functional Areas (semicolon-separated list) +- Priority (Critical, High, Medium, Low) +- **Priority Score** (1-5, used for calculating averages) +- Labels +- URL + +This CSV can be imported into Excel, Google Sheets, or other data analysis tools for custom filtering and visualization. + +## Summary Statistics (OPEN ISSUES ONLY) + +- **Total Open Issues:** 92 +- **Analysis Date:** February 3, 2026 +- **Date Range:** Since January 1, 2025 + +### By Type +- **Bugs:** 16 open +- **Features:** 10 open +- **Questions:** 5 open +- **Other:** 61 open + +### By Priority +- **Critical:** 9 open +- **High:** 27 open +- **Medium:** 46 open +- **Low:** 10 open + +### Top Functional Areas (by priority) +1. **Validation** - 25 issues (Avg Priority: 3.64) +2. **Jackson** - 17 issues (Avg Priority: 3.59) +3. **Dependencies** - 21 issues (Avg Priority: 3.57) +4. **Jakarta Migration** - 20 issues (Avg Priority: 3.55) +5. **Annotation Processing** - 63 issues (Avg Priority: 3.33) + +## How Priorities Are Determined + +### Priority Scoring System + +We use a **weighted scoring methodology** that analyzes issue content and labels: + +| Priority Level | Score | Criteria | +|---------------|-------|----------| +| **Critical** | 5 | Regressions, breaking changes, P0/P1 labels | +| **High** | 4 | Exceptions, crashes, bugs | +| **Medium** | 3 | Standard issues, general improvements | +| **Low** | 2 | Feature requests, enhancements | +| **Low** | 1 | Questions, documentation | + +**Average Priority Score** is calculated for each functional area to identify which areas need the most urgent attention. + +## ⭐ Combined Approach: The Best Way to Prioritize + +The **Combined Approach** merges functional areas (Approach 2) with priority levels (Approach 3) to answer: + +**"Which functional area should we focus on first?"** + +### How It Works + +1. Each issue is assigned to one or more functional areas +2. Each issue receives a priority score (1-5) +3. For each functional area, we calculate: + - Total issue count + - Count by priority level (Critical, High, Medium, Low) + - **Average priority score** +4. Areas are ranked by average priority score + +### Example + +| Functional Area | Total | Avg Score | Critical | High | Medium | Low | +|----------------|-------|-----------|----------|------|--------|-----| +| Validation | 25 | **3.64** | 5 | 9 | 8 | 3 | +| Jackson | 17 | **3.59** | 2 | 7 | 7 | 1 | + +**Interpretation:** Validation has more issues (25 vs 17) AND a higher average priority (3.64 vs 3.59), making it the top priority area. + +## How to Use + +### For Quick Triage +Use the **Combined Approach** table in `ISSUES_ANALYSIS_2025_OPEN.md`: +1. Find the functional area with the highest average priority score +2. Within that area, tackle Critical issues first, then High +3. Move to the next functional area when done + +### For Team Assignment +1. Assign specialized team members to high-priority functional areas +2. Examples: + - Annotation expert → Annotation Processing (63 issues, 3.33 avg) + - Jakarta expert → Jakarta Migration (20 issues, 3.55 avg) + - Jackson expert → Jackson (17 issues, 3.59 avg) + +### For Sprint Planning +1. Choose top 2-3 functional areas by average priority score +2. Pull Critical and High priority issues from those areas +3. Plan capacity accordingly + +### For Custom Analysis +Use **ISSUES_DATA_2025_OPEN.csv** to: +- Create pivot tables by Priority + Functional Area +- Filter to specific combinations (e.g., "Critical + Validation") +- Generate charts showing priority distribution +- Track trends over time (re-run monthly) + +## Recommendations + +Based on the combined priority analysis: + +### 🔴 Immediate Focus +1. **Validation** (3.64 avg) - 5 critical issues need fixes +2. **Jackson** (3.59 avg) - 2 critical issues +3. **Dependencies** (3.57 avg) - 5 critical issues + +### 🟠 High Priority +4. **Jakarta Migration** (3.55 avg) - Complete migration effort +5. **Annotation Processing** (3.33 avg) - Highest volume (63 issues) + +### 🟡 Medium Priority +6. **Kotlin**, **Polymorphic Types**, **Examples** - Address after above + +### Strategy +- Focus on top-ranked areas first +- Within each area, prioritize Critical → High → Medium → Low +- Re-run analysis monthly to track improvement + +## Key Differences from Previous Analysis + +| Previous (All Issues) | New (Open Only) | +|----------------------|-----------------| +| 155 total issues | 92 open issues | +| Included closed issues | Open issues only | +| 3 approaches | 4 approaches (added Combined) | +| Basic priority labels | Weighted priority scoring | +| No priority methodology | Detailed scoring system | +| Separate approaches | Combined Approach 2+3 | + +## Analysis Methodology + +1. **Data Collection:** GitHub API query for issues since 2025-01-01 with state=OPEN +2. **Categorization:** Keyword matching on titles and bodies +3. **Priority Scoring:** Multi-factor analysis (labels, keywords, issue type) +4. **Calculation:** Average priority scores per functional area +5. **Ranking:** Sort functional areas by average priority score + +For questions or updates, please open an issue in the repository. diff --git a/ISSUES_DATA_2025_OPEN.csv b/ISSUES_DATA_2025_OPEN.csv new file mode 100644 index 0000000000..fd47fd84a9 --- /dev/null +++ b/ISSUES_DATA_2025_OPEN.csv @@ -0,0 +1,93 @@ +Issue Number,Title,Type,Functional Areas,Priority,Priority Score,Labels,URL +5045,[Feature]: Need since or reason field in @Hidden annotation,Feature,Annotation Processing,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/5045 +5043,[Bug]: AnnotatedType equality in ModelConverterContextImpl,Bug,Jakarta Migration; Annotation Processing; Validation,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5043 +5036,[Bug]: Example text is truncated when beginning with numbers,Bug,Annotation Processing; Validation; Examples,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5036 +5035,[Bug]: Jakarta @Positive validation is not present in Swagger,Bug,Jakarta Migration; Validation,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5035 +5028,[Bug]: Polymorphic types don't include composite schema reference,Bug,Polymorphic Types; Jackson; Dependencies,Critical,5,Bug,https://github.com/swagger-api/swagger-core/issues/5028 +5027,""required" property in Schema.java should be a Set (SortedSet for example), not a List",Other,Validation; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/5027 +5017,[Bug]: OpenAPI 3.1: Enum used in @Schema#propertyNames removed when filtering unreferenced schemas,Bug,Annotation Processing; Examples,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5017 +5016,[Question]: Duplicate schema names don't throw but are overwritten,Question,Annotation Processing,High,4,Question,https://github.com/swagger-api/swagger-core/issues/5016 +5014,[Question]: How to specify @Schema.examples where each element is an array?,Question,Annotation Processing; Examples,Low,1,Question,https://github.com/swagger-api/swagger-core/issues/5014 +5013,[Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1,Bug,Annotation Processing; Dependencies,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5013 +5012,[Bug]: The OAS 3.1 is missing information from the @ArraysSchema.arraySchema,Bug,Annotation Processing; Examples; Dependencies,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5012 +5011,[Feature]: Drop commons-lang3 dependency and replace its usages with core Java,Feature,Dependencies,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/5011 +5007,[Bug]: kotlin inline classes produce weird field names,Bug,Jakarta Migration; Annotation Processing; Jackson; Kotlin; Dependencies,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5007 +5001,[Bug]: Native support for Jakarta @Nullable annotation to generate proper OAS 3.1 nullable types,Bug,Jakarta Migration; Annotation Processing; Validation; Examples; Dependencies,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/5001 +4999,[Bug]: Example value starting with a number is parsed incorrectly,Bug,Jakarta Migration; Annotation Processing; Examples,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/4999 +4993,[Bug]: Regression: class specified in @ArraySchema.schema.implementation not rendered in schemas,Bug,Annotation Processing; Dependencies,Critical,5,Bug,https://github.com/swagger-api/swagger-core/issues/4993 +4991,[Feature] Support Jackson 3.x release line,Feature,Jackson,Critical,5,Feature,https://github.com/swagger-api/swagger-core/issues/4991 +4984,[Question]: Duplicate records if Class and Operation both has @Path param,Question,Jakarta Migration; Annotation Processing; Examples; Dependencies,Low,1,Question,https://github.com/swagger-api/swagger-core/issues/4984 +4976,[Feature]: Reduce Boilerplate in swagger-core Models (Optional Lombok Support or Alternatives),Feature,Other,High,4,Feature,https://github.com/swagger-api/swagger-core/issues/4976 +4966,[Feature]: Provide a bom module for managing dependencies,Feature,Examples; Dependencies,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/4966 +4963,[Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string,Bug,Annotation Processing,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/4963 +4960,[Bug]: SpecFilter skips the ApiResponse#$ref field,Bug,Annotation Processing; Validation,High,4,Bug,https://github.com/swagger-api/swagger-core/issues/4960 +4951,[Feature]: support for runtime skip properties inside ModelConverter,Feature,Other,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/4951 +4939,Integer enum Schema parsing can fail based upon locale,Question,Examples,Low,1,Question,https://github.com/swagger-api/swagger-core/issues/4939 +4935,Jackson dependency update results in "java 8 date/time type java.time.LocalDateTime not supported by default",Question,Jakarta Migration; Annotation Processing; Examples; Jackson; Dependencies,High,4,Question,https://github.com/swagger-api/swagger-core/issues/4935 +4928,Lack of Friendly Support for Parameter Validation Grouping,Other,Jakarta Migration; Annotation Processing; Validation; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4928 +4924,Ability to remove unused definitions from generated YML,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4924 +4923,Custom UUID wrapper class can't be used anymore after 2.2.28,Other,Annotation Processing; Examples,High,4,,https://github.com/swagger-api/swagger-core/issues/4923 +4910,Create an annotation the add at controller level to summarize information regarding failed http responses.,Other,Annotation Processing; Validation; Examples,Critical,5,,https://github.com/swagger-api/swagger-core/issues/4910 +4909,Custom NotNull annotations stopped working between 2.2.28 and 2.2.29,Other,Jakarta Migration; Annotation Processing; Validation,Critical,5,,https://github.com/swagger-api/swagger-core/issues/4909 +4908,defaultValue attribute at enum object generate arbitrary json file,Other,Jakarta Migration; Annotation Processing; Examples; Dependencies,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4908 +4906,java.lang.Object converted to json object (map) type,Other,Other,High,4,,https://github.com/swagger-api/swagger-core/issues/4906 +4905,CustomResolver's Results get overwritten by default ModelResolver,Other,Annotation Processing; Jackson,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4905 +4904,java.lang.ClassCastException: class io.swagger.v3.oas.models.media.JsonSchema cannot be cast to class io.swagger.v3.oas.models.media.ComposedSchema,Other,Jackson,High,4,,https://github.com/swagger-api/swagger-core/issues/4904 +4903,jackson module not working in 2.2.30,Other,Jakarta Migration; Jackson,High,4,,https://github.com/swagger-api/swagger-core/issues/4903 +4887,Order of `required` properties,Other,Validation,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4887 +4886,Validation Meta annotations not working,Other,Jakarta Migration; Annotation Processing; Validation; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4886 +4882,swagger-maven-plugin: OPERATION annotation with multiple TAGS does not correctly generate openapi.json using inheritance in Java,Other,Polymorphic Types; Annotation Processing; Dependencies,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4882 +4877,2.2.30 - @NotNull(jakarta.validation.constraints.NotNull) assigned to a group should treat field as mandatory,Other,Jakarta Migration; Validation,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4877 +4864,generate OpenApi yml file with swagger-maven-plugin and with Java 17 #903,Other,Annotation Processing; Dependencies,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4864 +4863,"Override" example value when extending a class,Other,Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4863 +4854,Bootstrapped servlet returns empty JSON as of 2.2.24,Other,Annotation Processing; Examples,High,4,,https://github.com/swagger-api/swagger-core/issues/4854 +4851,The example value of the request body in swagger has a "string" value,Other,Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4851 +4848,ModelResolver#resolve ignores TYPE_USE annotations on property types,Other,Annotation Processing; Jackson,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4848 +4847,@Schema annotation on custom string type is ignored when using @JsonValue,Other,Annotation Processing; Jackson,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4847 +4846,Swagger adds extra line breaks in yaml generated from annotated code,Other,Jakarta Migration; Annotation Processing; Examples; Dependencies,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4846 +4844,swagger-annotations: Add annotations to support x-enum-descriptions and x-enum-varnames,Other,Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4844 +4843,OpenApi not generated when resourceClasses used,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4843 +4842,OpenApi doc not beeing generated properly,Other,Jakarta Migration; Annotation Processing; Validation; Examples; Jackson; Dependencies,High,4,,https://github.com/swagger-api/swagger-core/issues/4842 +4841,2.2.27 & 2.2.28: org.gradle.api.internal.DefaultMutationGuard$IllegalMutationException: Project#afterEvaluate(Action) on project ':XX' cannot be executed in the current context.,Bug,Validation; Dependencies,Critical,5,"Bug, P1",https://github.com/swagger-api/swagger-core/issues/4841 +4840,[Feature] Mark type as deprecated if the class is `@Deprecated`,Feature,Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4840 +4839,[Feature/Bug] Forbid mutliple `@ApiResponse` annotations with the same response code,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4839 +4838,Empty default values are ignored,Feature,Annotation Processing; Validation,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/4838 +4837,Is it possible to convert from OAS 3.0 to OAS 3.1 using this lib?,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4837 +4824,Bill of material,Other,Jakarta Migration; Annotation Processing; Dependencies,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4824 +4820,"@Schema(example="1234", type="string") interpreted as integer",Other,Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4820 +4819,Definition for parent interface not generated,Other,Polymorphic Types; Annotation Processing; Validation; Jackson,High,4,,https://github.com/swagger-api/swagger-core/issues/4819 +4813,Upgrade to v2.2.27: Cannot change dependencies of dependency configuration '' after it has been included in dependency resolution,Bug,Dependencies,Critical,5,"Bug, P1",https://github.com/swagger-api/swagger-core/issues/4813 +4789,Classes / enums with same name but different package replace each other,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4789 +4763,Explicit schema type specified on `@Parameter` annotation is always ignored,Other,Jakarta Migration; Annotation Processing; Validation; Dependencies,High,4,,https://github.com/swagger-api/swagger-core/issues/4763 +4753,@Schema field-level description ignored when using custom type with $ref #2723,Other,Jakarta Migration; Annotation Processing; Validation; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4753 +4711,@Schema is processed without enum when implementation and allowableValues exist at the same time,Other,Jakarta Migration; Annotation Processing; Validation,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4711 +4696,Using @JsonUnwrapped with @Schema(implementation = Something) does not unwrap,Other,Annotation Processing; Jackson,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4696 +4689,BUG Unable to deserialize OpenAPI Parameter,Other,Validation,High,4,,https://github.com/swagger-api/swagger-core/issues/4689 +4682,BUG properties of type Object do not have any type information when generating open api 3.1.0,Bug,Examples; Jackson,High,4,"Bug, P2, pull-request-welcome, 3.1 spec support",https://github.com/swagger-api/swagger-core/issues/4682 +4649,Generated but not references ResponseEntity*** type in schema if rest-api-class is using spring's ResponseEntity,Other,Jakarta Migration; Annotation Processing; Validation; Examples; Dependencies,Critical,5,,https://github.com/swagger-api/swagger-core/issues/4649 +4555,Could `@Schema(nullable = true)` work when outputting OpenAPI 3.1.0?,Other,Annotation Processing; Validation,Critical,5,,https://github.com/swagger-api/swagger-core/issues/4555 +4506,Jackson @JsonFormat doesn't support Enum type,Other,Jackson; Kotlin,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4506 +4404,Add support for more java.time objects,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4404 +4358,Incorrect mapping of sub-classes when nested as member of another sub-class,Other,Polymorphic Types; Annotation Processing; Examples,High,4,,https://github.com/swagger-api/swagger-core/issues/4358 +4355,@ApiResponse cannot infer parametrised type with Java Generics ,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4355 +4352,Inconsistent behaviour for oneOf,Other,Polymorphic Types; Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4352 +4330,Missing oneOf sections for polymorphic schema,Other,Polymorphic Types; Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4330 +4244,Ignore JAX-RS method parameters with specific annotations,Other,Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4244 +4156,Sealed kotlin class with oneOf annotation generates a type: object,Other,Polymorphic Types; Annotation Processing; Jackson; Kotlin,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4156 +4061,@Schema not working for boolean fields in Java,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/4061 +3818,Maps that use enums as keys don't explicitly declare them in the resulting swagger def.,Other,Annotation Processing; Validation; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3818 +3689,@ArraySchema is ignored in model property (array of abstract class),Other,Polymorphic Types; Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3689 +3677,How to prevent oneOf() on supertypes leading to recursion in subtypes?,Other,Polymorphic Types; Annotation Processing; Examples; Jackson,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3677 +3577,[bug] Integer enum support,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3577 +3567,Question: Is there a way to specify allowableValues dynamically?,Other,Polymorphic Types; Annotation Processing; Examples,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3567 +3556,Multiple SecurityRequirements annotations with AND condition,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3556 +3530,Getting StackOverflowError on ModelResolver,Other,Annotation Processing,High,4,,https://github.com/swagger-api/swagger-core/issues/3530 +3496,Swagger does not serializes Generic Objects in API response completely.,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3496 +3411,Consider the @JsonSubTypes for generating the discriminator mapping,Feature,Polymorphic Types; Annotation Processing; Validation; Jackson; Dependencies,Low,2,"Feature, Workaround available, P2, :thumbsup: Top Issue!",https://github.com/swagger-api/swagger-core/issues/3411 +3323,Generic Response Types,Feature,Annotation Processing; Validation; Examples,Low,2,Feature,https://github.com/swagger-api/swagger-core/issues/3323 +3089,Can't reference javax.ws.rs.core.Response.Status enum in @ApiResponse.responseCode,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/3089 +3025,"openapi.json fails to take into account servlet context path, produces bad spec file",Other,Other,High,4,,https://github.com/swagger-api/swagger-core/issues/3025 +2998,ApiImplicitParam and ApiImplicitParams for Swagger 2.X,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/2998 +2961,Field with first letter lower case not recognized,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/2961 +2844,disable global security for particular operation,Other,Annotation Processing,Medium,3,,https://github.com/swagger-api/swagger-core/issues/2844 +2192,Field name is getting generated wrongly if field type is "Boolean" (wrapper class for boolean) instead of primitive "boolean" type,Other,Other,Medium,3,,https://github.com/swagger-api/swagger-core/issues/2192 diff --git a/PRS_ANALYSIS_2025_OPEN.md b/PRS_ANALYSIS_2025_OPEN.md new file mode 100644 index 0000000000..01274fe0ec --- /dev/null +++ b/PRS_ANALYSIS_2025_OPEN.md @@ -0,0 +1,554 @@ +# Swagger-Core Open Pull Requests Analysis (2025) + +**Analysis Date:** 2026-02-03 +**Total Open PRs Analyzed:** 25 +**Date Range:** Since January 1, 2025 + +--- + +## Executive Summary + +This analysis examines **25 OPEN pull requests** submitted to the swagger-api/swagger-core repository since January 1, 2025. The PRs have been categorized using the same approaches used for issues analysis: + +1. **By PR Type** - Categorization by change type (Bug Fix, Feature, Refactor, etc.) +2. **By Functional Area** - Groups by technical domain for specialized review assignment +3. **By Priority** - Prioritizes work based on impact and urgency +4. **Combined: Functional Areas by Priority** ⭐ - Shows which functional areas have the highest priority PRs + +--- + +## How Priorities Are Determined + +Priority is calculated using a **weighted scoring system** specific to pull requests: + +### Priority Scoring Methodology for PRs + +| Priority Level | Score | Criteria | +|---------------|-------|----------| +| **High** | 4 | • Bug fixes (especially regressions)
• Critical fixes
• Keywords: "fix:", "bug fix", "regression", "crash", "exception" | +| **Medium** | 3 | • Features
• Refactors
• General improvements | +| **Low** | 2 | • Tests
• Documentation | +| **Low** | 1 | • Chores
• Build improvements | + +**Average Priority Score** for each functional area is calculated as the mean of all PR scores in that area. This helps identify which functional areas have the most high-priority pending changes. + +--- + +## Approach 1: By PR Type + +This approach groups PRs by their change type. **OPEN PRS ONLY.** + +### Summary Statistics + +**Bug Fix:** 7 open +**Feature:** 6 open +**Refactor:** 1 open +**Test:** 1 open +**Other:** 10 open + + +### Detailed Breakdown + +#### Bug Fix (7 open PRs) + +- #5049: fix: add missing @ArraysSchema.arraySchema properties (by @Mattias-Sehlstedt) +- #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +- #5020: bug fix propertyNames schema is not removed as unreferenced by SpecFilter #5017 (by @OllieKosh) +- #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4977: fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas (by @kuntal1461) +- #4954: fix: Java Byte to OAS integer data type (by @JongminChung) + +#### Feature (6 open PRs) + +- #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +- #5037: feat: change Schema.required from List to Set (#5027) (by @yht0827) +- #5031: feat: migrate to jackson 3 (by @vpelikh) +- #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +- #4983: feat: Infer discriminator mapping (by @PatrickFeiring) +- #4974: feat: allow empty string as defaultValue in @Schema (by @juntae6942) + +#### Refactor (1 open PRs) + +- #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) + +#### Test (1 open PRs) + +- #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) + +#### Other (10 open PRs) + +- #5050: Analyze 2025 open issues with combined functional area + priority ranking (by @Copilot) +- #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4997: Add parameter ignoreHidden (by @jobayle) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4985: Add support for jspecify annotations (by @weberhofer) +- #4962: MCP Server Opsera (by @balamuralipopsera) +- #4961: MCP Server for Swagger Core (by @Vishnu-Opsera) +- #4861: Added ability to set name for ApiResponse and RequestBody annotations (by @altro3) +- #4821: Add DurationSchema for java.time.Duration as PrimitiveType (by @MoellJ) + +--- + +## Approach 2: By Functional Area + +This approach groups PRs by technical domain and functionality. **OPEN PRS ONLY.** + +### Summary Statistics (sorted by PR count) + +**Annotation Processing:** 16 open PRs +**Validation:** 10 open PRs +**Jakarta Migration:** 5 open PRs +**Examples:** 4 open PRs +**Jackson:** 4 open PRs +**OAS 3.1:** 4 open PRs +**Other:** 4 open PRs +**Dependencies:** 3 open PRs +**SpecFilter:** 2 open PRs +**Polymorphic Types:** 1 open PRs + +### Detailed Breakdown + +#### Annotation Processing (16 open PRs) + +*PRs related to @Schema, @ArraySchema, @Hidden, and other annotations* + +🟠 #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +🟠 #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +🟠 #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +🟠 #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +🟠 #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +🟢 #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) +🟠 #4997: Add parameter ignoreHidden (by @jobayle) +🟠 #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +🟠 #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +🟠 #4985: Add support for jspecify annotations (by @weberhofer) +🟠 #4983: feat: Infer discriminator mapping (by @PatrickFeiring) +🟠 #4977: fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas (by @kuntal1461) +🟠 #4974: feat: allow empty string as defaultValue in @Schema (by @juntae6942) +🟠 #4954: fix: Java Byte to OAS integer data type (by @JongminChung) + +... and 1 more PRs + +#### Validation (10 open PRs) + +*PRs with validation annotations, required fields, and RequiredMode* + +🟠 #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +🟠 #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +🟠 #5037: feat: change Schema.required from List to Set (#5027) (by @yht0827) +🟠 #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +🟠 #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +🟢 #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +🟠 #4985: Add support for jspecify annotations (by @weberhofer) +🟠 #4974: feat: allow empty string as defaultValue in @Schema (by @juntae6942) +🟡 #4861: Added ability to set name for ApiResponse and RequestBody annotations (by @altro3) + +#### Jakarta Migration (5 open PRs) + +*PRs related to Jakarta namespace migration and Jakarta annotations* + +🟠 #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +🟠 #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +🟠 #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +🟠 #4985: Add support for jspecify annotations (by @weberhofer) + +#### Examples (4 open PRs) + +*PRs with example values and documentation generation* + +🟠 #5049: fix: add missing @ArraysSchema.arraySchema properties (by @Mattias-Sehlstedt) +🟠 #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +🟠 #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) + +#### Jackson (4 open PRs) + +*PRs with Jackson annotations and serialization/deserialization* + +🟠 #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +🟠 #5031: feat: migrate to jackson 3 (by @vpelikh) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +🟠 #4983: feat: Infer discriminator mapping (by @PatrickFeiring) + +#### OAS 3.1 (4 open PRs) + +*PRs related to OpenAPI 3.1 specification support* + +🟠 #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +🟠 #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +🟠 #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +🟠 #4954: fix: Java Byte to OAS integer data type (by @JongminChung) + +#### Other (4 open PRs) + +🟡 #5050: Analyze 2025 open issues with combined functional area + priority ranking (by @Copilot) +🟠 #4962: MCP Server Opsera (by @balamuralipopsera) +🟠 #4961: MCP Server for Swagger Core (by @Vishnu-Opsera) +🟡 #4821: Add DurationSchema for java.time.Duration as PrimitiveType (by @MoellJ) + +#### Dependencies (3 open PRs) + +*PRs with dependencies, Maven/Gradle plugins, and build processes* + +🟠 #4997: Add parameter ignoreHidden (by @jobayle) +🟠 #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +🟠 #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) + +#### SpecFilter (2 open PRs) + +*PRs related to filtering and removing unreferenced schemas* + +🟠 #5020: bug fix propertyNames schema is not removed as unreferenced by SpecFilter #5017 (by @OllieKosh) +🟠 #4977: fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas (by @kuntal1461) + +#### Polymorphic Types (1 open PRs) + +*PRs with oneOf, allOf, discriminators, and class hierarchies* + +🟠 #4983: feat: Infer discriminator mapping (by @PatrickFeiring) + +--- + +## Approach 3: By Priority + +This approach prioritizes PRs based on their impact and urgency. **OPEN PRS ONLY.** + +### Priority Levels + +**High:** 21 open PRs +**Medium:** 3 open PRs +**Low:** 1 open PRs + +### Detailed Breakdown + +#### High Priority (21 open PRs) + +- #5049: fix: add missing @ArraysSchema.arraySchema properties (by @Mattias-Sehlstedt) +- #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +- #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +- #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +- #5037: feat: change Schema.required from List to Set (#5027) (by @yht0827) +- #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +- #5031: feat: migrate to jackson 3 (by @vpelikh) +- #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +- #5020: bug fix propertyNames schema is not removed as unreferenced by SpecFilter #5017 (by @OllieKosh) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4997: Add parameter ignoreHidden (by @jobayle) +- #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4985: Add support for jspecify annotations (by @weberhofer) +- #4983: feat: Infer discriminator mapping (by @PatrickFeiring) +- #4977: fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas (by @kuntal1461) +- #4974: feat: allow empty string as defaultValue in @Schema (by @juntae6942) +- #4962: MCP Server Opsera (by @balamuralipopsera) +- #4961: MCP Server for Swagger Core (by @Vishnu-Opsera) + +... and 1 more PRs + +#### Medium Priority (3 open PRs) + +- #5050: Analyze 2025 open issues with combined functional area + priority ranking (by @Copilot) +- #4861: Added ability to set name for ApiResponse and RequestBody annotations (by @altro3) +- #4821: Add DurationSchema for java.time.Duration as PrimitiveType (by @MoellJ) + +#### Low Priority (1 open PRs) + +- #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) + +--- + +## ⭐ Combined Approach: Functional Areas by Priority + +This approach **combines Approach 2 and Approach 3** to show which functional areas have the highest priority PRs. This helps answer: **"Which functional area should we review first?"** + +### Functional Areas Ranked by Average Priority Score + +The table below shows each functional area ranked by its average priority score, along with the distribution of PR priorities. + +| Rank | Functional Area | Total | Avg Score | High | Medium | Low | Priority Level | +|------|----------------|-------|-----------|------|--------|-----|----------------| +| 1 | **Jakarta Migration** | 5 | **4.00** | 5 | 0 | 0 | 🟠 HIGH | +| 2 | **Polymorphic Types** | 1 | **4.00** | 1 | 0 | 0 | 🟠 HIGH | +| 3 | **Examples** | 4 | **4.00** | 4 | 0 | 0 | 🟠 HIGH | +| 4 | **Jackson** | 4 | **4.00** | 4 | 0 | 0 | 🟠 HIGH | +| 5 | **Dependencies** | 3 | **4.00** | 3 | 0 | 0 | 🟠 HIGH | +| 6 | **OAS 3.1** | 4 | **4.00** | 4 | 0 | 0 | 🟠 HIGH | +| 7 | **SpecFilter** | 2 | **4.00** | 2 | 0 | 0 | 🟠 HIGH | +| 8 | **Annotation Processing** | 16 | **3.81** | 14 | 1 | 1 | 🟠 HIGH | +| 9 | **Validation** | 10 | **3.70** | 8 | 1 | 1 | 🟡 MEDIUM | +| 10 | **Other** | 4 | **3.50** | 2 | 2 | 0 | 🟡 MEDIUM | + + +### Interpretation Guide + +- **Avg Score:** Higher scores (closer to 4.0) indicate more urgent PRs +- **Priority Level:** + - 🟠 HIGH (3.8+): Review and merge soon + - 🟡 MEDIUM (3.0-3.7): Standard priority + - 🟢 LOW (<3.0): Can be deferred + +### Key Insights from Combined Analysis + +**Top 3 Priority Areas:** + +1. **Jakarta Migration** (Avg: 4.00) + - 5 open PRs + - 5 high priority, 0 medium + - High priority PRs: #5044, #5018, #4987, +2 more + +2. **Polymorphic Types** (Avg: 4.00) + - 1 open PRs + - 1 high priority, 0 medium + - High priority PRs: #4983 + +3. **Examples** (Avg: 4.00) + - 4 open PRs + - 4 high priority, 0 medium + - High priority PRs: #5049, #5048, #4987, +1 more + + +**Recommendation:** Focus review effort on the top-ranked functional areas, starting with their High priority PRs. + +## Summary: All Open PRs + +This section provides a complete list of all open PRs for quick reference. + +| # | PR | Type | Priority | Functional Areas | Author | +|---|-----|------|----------|------------------|---------| +| 1 | [#5050](https://github.com/swagger-api/swagger-core/pull/5050) | Other | 🟡 Medium | Other | @Copilot | +| 2 | [#5049](https://github.com/swagger-api/swagger-core/pull/5049) | Bug Fix | 🟠 High | Examples | @Mattias-Sehlstedt | +| 3 | [#5048](https://github.com/swagger-api/swagger-core/pull/5048) | Other | 🟠 High | Annotation Processing, Examples | @Mattias-Sehlstedt | +| 4 | [#5047](https://github.com/swagger-api/swagger-core/pull/5047) | Refactor | 🟠 High | Annotation Processing, Validation, ... | @Mattias-Sehlstedt | +| 5 | [#5044](https://github.com/swagger-api/swagger-core/pull/5044) | Feature | 🟠 High | Jakarta Migration, Validation | @NaMinhyeok | +| 6 | [#5037](https://github.com/swagger-api/swagger-core/pull/5037) | Feature | 🟠 High | Validation | @yht0827 | +| 7 | [#5034](https://github.com/swagger-api/swagger-core/pull/5034) | Bug Fix | 🟠 High | Annotation Processing, OAS 3.1 | @xeulbn | +| 8 | [#5031](https://github.com/swagger-api/swagger-core/pull/5031) | Feature | 🟠 High | Jackson | @vpelikh | +| 9 | [#5025](https://github.com/swagger-api/swagger-core/pull/5025) | Feature | 🟠 High | Annotation Processing, Validation | @Olfi01 | +| 10 | [#5020](https://github.com/swagger-api/swagger-core/pull/5020) | Bug Fix | 🟠 High | SpecFilter | @OllieKosh | +| 11 | [#5018](https://github.com/swagger-api/swagger-core/pull/5018) | Other | 🟠 High | Jakarta Migration, Annotation Processing, ... | @zdary | +| 12 | [#5015](https://github.com/swagger-api/swagger-core/pull/5015) | Test | 🟢 Low | Annotation Processing, Validation | @ewaostrowska | +| 13 | [#4997](https://github.com/swagger-api/swagger-core/pull/4997) | Other | 🟠 High | Annotation Processing, Dependencies | @jobayle | +| 14 | [#4989](https://github.com/swagger-api/swagger-core/pull/4989) | Bug Fix | 🟠 High | Annotation Processing, OAS 3.1 | @K5qu4r3d | +| 15 | [#4987](https://github.com/swagger-api/swagger-core/pull/4987) | Other | 🟠 High | Jakarta Migration, Annotation Processing, ... | @kuntal1461 | +| 16 | [#4986](https://github.com/swagger-api/swagger-core/pull/4986) | Bug Fix | 🟠 High | Jakarta Migration, Annotation Processing, ... | @kuntal1461 | +| 17 | [#4985](https://github.com/swagger-api/swagger-core/pull/4985) | Other | 🟠 High | Jakarta Migration, Annotation Processing, ... | @weberhofer | +| 18 | [#4983](https://github.com/swagger-api/swagger-core/pull/4983) | Feature | 🟠 High | Polymorphic Types, Annotation Processing, ... | @PatrickFeiring | +| 19 | [#4977](https://github.com/swagger-api/swagger-core/pull/4977) | Bug Fix | 🟠 High | Annotation Processing, SpecFilter | @kuntal1461 | +| 20 | [#4974](https://github.com/swagger-api/swagger-core/pull/4974) | Feature | 🟠 High | Annotation Processing, Validation | @juntae6942 | +| 21 | [#4962](https://github.com/swagger-api/swagger-core/pull/4962) | Other | 🟠 High | Other | @balamuralipopsera | +| 22 | [#4961](https://github.com/swagger-api/swagger-core/pull/4961) | Other | 🟠 High | Other | @Vishnu-Opsera | +| 23 | [#4954](https://github.com/swagger-api/swagger-core/pull/4954) | Bug Fix | 🟠 High | Annotation Processing, OAS 3.1 | @JongminChung | +| 24 | [#4861](https://github.com/swagger-api/swagger-core/pull/4861) | Other | 🟡 Medium | Annotation Processing, Validation | @altro3 | +| 25 | [#4821](https://github.com/swagger-api/swagger-core/pull/4821) | Other | 🟡 Medium | Other | @MoellJ | + +--- + +--- + +## Detailed Priority Breakdown by Functional Area + +This section provides detailed listings of PRs in each functional area, grouped by priority. + +### Jakarta Migration +**Total:** 5 | **Avg Score:** 4.00 | High: 5 | Medium: 0 | Low: 0 + +**🟠 High Priority (5 PRs):** +- #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4985: Add support for jspecify annotations (by @weberhofer) + +--- + +### Polymorphic Types +**Total:** 1 | **Avg Score:** 4.00 | High: 1 | Medium: 0 | Low: 0 + +**🟠 High Priority (1 PRs):** +- #4983: feat: Infer discriminator mapping (by @PatrickFeiring) + +--- + +### Examples +**Total:** 4 | **Avg Score:** 4.00 | High: 4 | Medium: 0 | Low: 0 + +**🟠 High Priority (4 PRs):** +- #5049: fix: add missing @ArraysSchema.arraySchema properties (by @Mattias-Sehlstedt) +- #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) + +--- + +### Jackson +**Total:** 4 | **Avg Score:** 4.00 | High: 4 | Medium: 0 | Low: 0 + +**🟠 High Priority (4 PRs):** +- #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +- #5031: feat: migrate to jackson 3 (by @vpelikh) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4983: feat: Infer discriminator mapping (by @PatrickFeiring) + +--- + +### Dependencies +**Total:** 3 | **Avg Score:** 4.00 | High: 3 | Medium: 0 | Low: 0 + +**🟠 High Priority (3 PRs):** +- #4997: Add parameter ignoreHidden (by @jobayle) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) + +--- + +### OAS 3.1 +**Total:** 4 | **Avg Score:** 4.00 | High: 4 | Medium: 0 | Low: 0 + +**🟠 High Priority (4 PRs):** +- #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +- #4954: fix: Java Byte to OAS integer data type (by @JongminChung) + +--- + +### SpecFilter +**Total:** 2 | **Avg Score:** 4.00 | High: 2 | Medium: 0 | Low: 0 + +**🟠 High Priority (2 PRs):** +- #5020: bug fix propertyNames schema is not removed as unreferenced by SpecFilter #5017 (by @OllieKosh) +- #4977: fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas (by @kuntal1461) + +--- + +### Annotation Processing +**Total:** 16 | **Avg Score:** 3.81 | High: 14 | Medium: 1 | Low: 1 + +**🟠 High Priority (14 PRs):** +- #5048: Ignore sibling logic if the property type is not a valid sibling candidate (by @Mattias-Sehlstedt) +- #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +- #5034: fix: OAS 3.1 schema generation for raw Object properties (by @xeulbn) +- #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4997: Add parameter ignoreHidden (by @jobayle) +- #4989: fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963) (by @K5qu4r3d) +- #4987: [Feature]: Provide a BOM module for managing dependencies (#4966) (by @kuntal1461) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4985: Add support for jspecify annotations (by @weberhofer) +- ... and 4 more + +**🟡 Medium Priority (1 PRs):** +- #4861: Added ability to set name for ApiResponse and RequestBody annotations (by @altro3) + +**🟢 Low Priority (1 PRs):** +- #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) + +--- + +### Validation +**Total:** 10 | **Avg Score:** 3.70 | High: 8 | Medium: 1 | Low: 1 + +**🟠 High Priority (8 PRs):** +- #5047: refactor: introduce class responsible for how bean validation annotations affect schemas (by @Mattias-Sehlstedt) +- #5044: feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation (by @NaMinhyeok) +- #5037: feat: change Schema.required from List to Set (#5027) (by @yht0827) +- #5025: feat: Multiple SecurityRequirement annotations with AND condition #3556 (by @Olfi01) +- #5018: 5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas (by @zdary) +- #4986: fix: resolve Validation Meta annotations not working (#4886) (by @kuntal1461) +- #4985: Add support for jspecify annotations (by @weberhofer) +- #4974: feat: allow empty string as defaultValue in @Schema (by @juntae6942) + +**🟡 Medium Priority (1 PRs):** +- #4861: Added ability to set name for ApiResponse and RequestBody annotations (by @altro3) + +**🟢 Low Priority (1 PRs):** +- #5015: Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working (by @ewaostrowska) + +--- + +### Other +**Total:** 4 | **Avg Score:** 3.50 | High: 2 | Medium: 2 | Low: 0 + +**🟠 High Priority (2 PRs):** +- #4962: MCP Server Opsera (by @balamuralipopsera) +- #4961: MCP Server for Swagger Core (by @Vishnu-Opsera) + +**🟡 Medium Priority (2 PRs):** +- #5050: Analyze 2025 open issues with combined functional area + priority ranking (by @Copilot) +- #4821: Add DurationSchema for java.time.Duration as PrimitiveType (by @MoellJ) + +--- + + +## Recommendations + +### Based on Combined Priority Analysis: + +1. **Review Focus (High Avg Score Areas):** + - Prioritize reviewing PRs in Jakarta Migration, Polymorphic Types, and OAS 3.1 areas + - These areas have the highest concentration of bug fixes and critical changes + +2. **Strategic Priorities:** + - **Jakarta Migration:** 5 PRs, all high priority - critical for ecosystem compatibility + - **Annotation Processing:** 16 PRs - highest volume, needs systematic review + - **Validation:** 10 PRs with 8 high priority - important for correctness + +3. **Review Approach:** + - Use the Combined Approach to select functional areas + - Within each area, review High priority PRs first (bug fixes) + - Schedule regular review sessions for each top-priority area + +### How to Use This Analysis: + +1. **For Review Planning:** Use the Combined Approach table to prioritize review efforts +2. **For Assignment:** Assign reviewers with domain expertise to corresponding functional areas +3. **For Merging:** Focus on merging High priority PRs from top-ranked areas first +4. **For Tracking:** Re-run analysis weekly to monitor PR backlog + +--- + +## Comparison with Issues Analysis + +Both issues and PRs show similar patterns: + +**Common High-Priority Areas:** +- Annotation Processing (63 issues, 16 PRs) +- Validation (25 issues, 10 PRs) +- Jakarta Migration (20 issues, 5 PRs) + +**Key Differences:** +- PRs have higher concentration of bug fixes (28% vs 17% for issues) +- PRs have more work in OAS 3.1 support (4 PRs, specific focus) +- Issues show more diversity in problem areas + +**Alignment Opportunity:** +Many open issues have corresponding PRs addressing them. Cross-reference to: +- Prioritize PR reviews that close high-priority issues +- Identify issues lacking PR coverage +- Track progress on critical functional areas + +--- + +## Conclusion + +The **Combined Approach** (Functional Areas by Priority) provides the best view for PR review decisions: + +- **What to review:** Functional areas with highest average priority scores +- **Within each area:** Start with High priority PRs (bug fixes) +- **Track progress:** Monitor both PR count and average priority score + +**Current Review Priorities (based on combined analysis):** +1. Jakarta Migration (4.00 avg) - 5 high priority PRs +2. Polymorphic Types (4.00 avg) - 1 high priority PR +3. Examples (4.00 avg) - 4 high priority PRs +4. Jackson (4.00 avg) - 4 high priority PRs (including Jackson 3 migration!) +5. Dependencies (4.00 avg) - 3 high priority PRs (including BOM module) + +All data is available in **PRS_DATA_2025_OPEN.csv** for further analysis. + diff --git a/PRS_ANALYSIS_README_OPEN.md b/PRS_ANALYSIS_README_OPEN.md new file mode 100644 index 0000000000..cfa53e3c17 --- /dev/null +++ b/PRS_ANALYSIS_README_OPEN.md @@ -0,0 +1,192 @@ +# Open Pull Requests Analysis for 2025 + +This directory contains analysis of **OPEN pull requests** submitted to the swagger-api/swagger-core repository since January 1, 2025. + +## Files + +### PRS_ANALYSIS_2025_OPEN.md ⭐ +A comprehensive markdown report containing: +- Analysis of **25 OPEN PRs only** +- **Four different categorization approaches** for grouping PRs: + 1. **By PR Type** - Change type categorization (Bug Fix, Feature, Refactor, etc.) + 2. **By Functional Area** - Technical domain-based grouping + 3. **By Priority** - Impact and urgency-based prioritization + 4. **⭐ Combined: Functional Areas by Priority** - Merges approaches 2 and 3 +- Detailed priority determination methodology for PRs +- Actionable recommendations for review priorities + +### PRS_DATA_2025_OPEN.csv ⭐ +A CSV file containing all **25 open PRs** with the following columns: +- PR Number +- Title +- Type (Bug Fix, Feature, Refactor, Test, Documentation, Chore, Other) +- Functional Areas (semicolon-separated list) +- Priority (High, Medium, Low) +- **Priority Score** (1-4, used for calculating averages) +- Author +- Created At +- URL + +This CSV can be imported into Excel, Google Sheets, or other data analysis tools for custom filtering and visualization. + +## Summary Statistics (OPEN PRS ONLY) + +- **Total Open PRs:** 25 +- **Analysis Date:** February 3, 2026 +- **Date Range:** Since January 1, 2025 + +### By Type +- **Bug Fix:** 7 open +- **Feature:** 6 open +- **Refactor:** 1 open +- **Test:** 1 open +- **Other:** 10 open + +### By Priority +- **High:** 21 open +- **Medium:** 3 open +- **Low:** 1 open + +### Top Functional Areas (by priority) +1. **Jakarta Migration** - 5 PRs (Avg Priority: 4.00) - ALL HIGH PRIORITY +2. **Polymorphic Types** - 1 PR (Avg Priority: 4.00) +3. **Examples** - 4 PRs (Avg Priority: 4.00) +4. **Jackson** - 4 PRs (Avg Priority: 4.00) - includes Jackson 3 migration! +5. **Dependencies** - 3 PRs (Avg Priority: 4.00) - includes BOM module +6. **Annotation Processing** - 16 PRs (Avg Priority: 3.81) + +## How Priorities Are Determined for PRs + +### Priority Scoring System for Pull Requests + +We use a **weighted scoring methodology** specific to PRs: + +| Priority Level | Score | Criteria | +|---------------|-------|----------| +| **High** | 4 | Bug fixes, critical fixes, regressions | +| **Medium** | 3 | Features, refactors, improvements | +| **Low** | 2 | Tests, documentation | +| **Low** | 1 | Chores, build improvements | + +**Average Priority Score** is calculated for each functional area to identify which areas have the most urgent PRs awaiting review. + +## ⭐ Combined Approach: The Best Way to Prioritize Reviews + +The **Combined Approach** merges functional areas (Approach 2) with priority levels (Approach 3) to answer: + +**"Which functional area should we review first?"** + +### How It Works + +1. Each PR is assigned to one or more functional areas +2. Each PR receives a priority score (1-4) +3. For each functional area, we calculate: + - Total PR count + - Count by priority level (High, Medium, Low) + - **Average priority score** +4. Areas are ranked by average priority score + +### Example + +| Functional Area | Total | Avg Score | High | Medium | Low | +|----------------|-------|-----------|------|--------|-----| +| Jakarta Migration | 5 | **4.00** | 5 | 0 | 0 | +| Jackson | 4 | **4.00** | 4 | 0 | 0 | + +**Interpretation:** Jakarta Migration has 5 PRs, all high priority (4.00 avg), making it the top priority for review. + +## How to Use + +### For Quick Review Triage +Use the **Combined Approach** table in `PRS_ANALYSIS_2025_OPEN.md`: +1. Find the functional area with the highest average priority score +2. Within that area, review High priority PRs first +3. Move to the next functional area when done + +### For Team Assignment +1. Assign specialized reviewers to high-priority functional areas +2. Examples: + - Jakarta expert → Jakarta Migration (5 PRs, all high priority) + - Jackson expert → Jackson (4 PRs, 4.00 avg, includes Jackson 3!) + - Annotation expert → Annotation Processing (16 PRs, 3.81 avg) + +### For Review Planning +1. Choose top 2-3 functional areas by average priority score +2. Schedule review sessions for High priority PRs +3. Plan capacity accordingly +4. Track weekly to monitor backlog + +### For Custom Analysis +Use **PRS_DATA_2025_OPEN.csv** to: +- Create pivot tables by Priority + Functional Area +- Filter to specific combinations (e.g., "High + Jakarta Migration") +- Generate charts showing priority distribution +- Track review progress over time (re-run weekly) + +## Recommendations + +Based on the combined priority analysis: + +### 🟠 Immediate Review Focus +1. **Jakarta Migration** (4.00 avg) - 5 PRs, all critical for ecosystem +2. **Jackson** (4.00 avg) - 4 PRs, includes Jackson 3 migration +3. **Examples** (4.00 avg) - 4 PRs, all bug fixes +4. **Dependencies** (4.00 avg) - 3 PRs, includes BOM module +5. **OAS 3.1** (4.00 avg) - 4 PRs, spec compliance fixes + +### 🟡 Standard Priority +6. **Annotation Processing** (3.81 avg) - 16 PRs, highest volume +7. **Validation** (3.70 avg) - 10 PRs, 8 high priority + +### Strategy +- Focus on areas with 4.00 avg score first (5 areas with perfect scores!) +- Within each area, prioritize: High → Medium → Low +- Re-run analysis weekly to track progress +- Cross-reference with open issues to prioritize PRs that close critical issues + +## Key Differences from Issues Analysis + +| Aspect | Issues | PRs | +|--------|--------|-----| +| Total (2025) | 92 open | 25 open | +| Bug/Fix % | 17% | 28% | +| Priority Distribution | More varied | Concentrated (84% high) | +| Top Area | Validation (3.64) | 5-way tie (4.00) | +| Review Action | Triage & assign | Review & merge | + +**Key Insight:** PRs are more action-oriented (bug fixes) while issues are more exploratory. Many PRs likely address open issues. + +## Alignment with Issues + +Cross-reference PRs with issues to: +- **Prioritize PRs closing critical issues** - Review PRs that resolve high-priority open issues first +- **Identify coverage gaps** - High-priority issues without PRs need attention +- **Track functional area progress** - Monitor both issue count and PR review rate + +## Analysis Methodology + +1. **Data Collection:** GitHub API query for PRs since 2025-01-01 with state=open +2. **Categorization:** Keyword matching on titles and descriptions +3. **Priority Scoring:** Based on PR type (bug fix = high, feature = medium, etc.) +4. **Calculation:** Average priority scores per functional area +5. **Ranking:** Sort functional areas by average priority score + +## Quick Start + +**For immediate action:** +1. Open `PRS_ANALYSIS_2025_OPEN.md` +2. Jump to "Combined Approach" section +3. See which functional area is ranked #1 +4. Review high priority PRs in that area +5. Start merging! + +**Current Top Priority:** 5-way tie at 4.00 avg: +- Jakarta Migration (5 PRs) +- Polymorphic Types (1 PR) +- Examples (4 PRs) +- Jackson (4 PRs) +- Dependencies (3 PRs) + +All areas have 100% high-priority PRs - focus on your area of expertise! + +For questions or updates, please open an issue in the repository. diff --git a/PRS_DATA_2025_OPEN.csv b/PRS_DATA_2025_OPEN.csv new file mode 100644 index 0000000000..27b05ca712 --- /dev/null +++ b/PRS_DATA_2025_OPEN.csv @@ -0,0 +1,26 @@ +PR Number,Title,Type,Functional Areas,Priority,Priority Score,Author,Created At,URL +5050,Analyze 2025 open issues with combined functional area + priority ranking,Other,Other,Medium,3,Copilot,2026-02-03T11:41:00Z,https://github.com/swagger-api/swagger-core/pull/5050 +5049,fix: add missing @ArraysSchema.arraySchema properties,Bug Fix,Examples,High,4,Mattias-Sehlstedt,2026-02-01T19:11:24Z,https://github.com/swagger-api/swagger-core/pull/5049 +5048,Ignore sibling logic if the property type is not a valid sibling candidate,Other,Annotation Processing; Examples,High,4,Mattias-Sehlstedt,2026-02-01T17:32:55Z,https://github.com/swagger-api/swagger-core/pull/5048 +5047,refactor: introduce class responsible for how bean validation annotations affect schemas,Refactor,Annotation Processing; Validation; Jackson,High,4,Mattias-Sehlstedt,2026-01-30T17:32:23Z,https://github.com/swagger-api/swagger-core/pull/5047 +5044,"feat: add support for Positive, PositiveOrZero, Negative, and NegativeOrZero constraints in model validation",Feature,Jakarta Migration; Validation,High,4,NaMinhyeok,2026-01-26T13:10:26Z,https://github.com/swagger-api/swagger-core/pull/5044 +5037,feat: change Schema.required from List to Set (#5027),Feature,Validation,High,4,yht0827,2026-01-17T03:10:23Z,https://github.com/swagger-api/swagger-core/pull/5037 +5034,fix: OAS 3.1 schema generation for raw Object properties,Bug Fix,Annotation Processing; OAS 3.1,High,4,xeulbn,2026-01-10T09:31:48Z,https://github.com/swagger-api/swagger-core/pull/5034 +5031,feat: migrate to jackson 3,Feature,Jackson,High,4,vpelikh,2026-01-01T13:41:09Z,https://github.com/swagger-api/swagger-core/pull/5031 +5025,feat: Multiple SecurityRequirement annotations with AND condition #3556,Feature,Annotation Processing; Validation,High,4,Olfi01,2025-11-26T15:06:43Z,https://github.com/swagger-api/swagger-core/pull/5025 +5020,bug fix propertyNames schema is not removed as unreferenced by SpecFilter #5017,Bug Fix,SpecFilter,High,4,OllieKosh,2025-11-18T19:31:20Z,https://github.com/swagger-api/swagger-core/pull/5020 +5018,5001: Add support for @Nullable annotations in OpenAPI 3.1 schemas,Other,Jakarta Migration; Annotation Processing; Validation; OAS 3.1,High,4,zdary,2025-11-17T01:07:53Z,https://github.com/swagger-api/swagger-core/pull/5018 +5015,Tests for issue #4341: ArraySchema.arraySchema.requiredMode not working,Test,Annotation Processing; Validation,Low,2,ewaostrowska,2025-11-06T11:00:53Z,https://github.com/swagger-api/swagger-core/pull/5015 +4997,Add parameter ignoreHidden,Other,Annotation Processing; Dependencies,High,4,jobayle,2025-10-16T08:03:32Z,https://github.com/swagger-api/swagger-core/pull/4997 +4989, fix: resolve PrimitiveType casting for OpenAPI 3.1 schemas (#4963),Bug Fix,Annotation Processing; OAS 3.1,High,4,K5qu4r3d,2025-10-07T19:05:34Z,https://github.com/swagger-api/swagger-core/pull/4989 +4987,[Feature]: Provide a BOM module for managing dependencies (#4966),Other,Jakarta Migration; Annotation Processing; Examples; Dependencies,High,4,kuntal1461,2025-10-07T18:18:34Z,https://github.com/swagger-api/swagger-core/pull/4987 +4986,fix: resolve Validation Meta annotations not working (#4886),Bug Fix,Jakarta Migration; Annotation Processing; Validation; Examples; Jackson; Dependencies,High,4,kuntal1461,2025-10-07T14:30:36Z,https://github.com/swagger-api/swagger-core/pull/4986 +4985,Add support for jspecify annotations,Other,Jakarta Migration; Annotation Processing; Validation,High,4,weberhofer,2025-10-07T14:23:44Z,https://github.com/swagger-api/swagger-core/pull/4985 +4983,feat: Infer discriminator mapping,Feature,Polymorphic Types; Annotation Processing; Jackson,High,4,PatrickFeiring,2025-10-04T12:23:13Z,https://github.com/swagger-api/swagger-core/pull/4983 +4977,fix(core): SpecFilter follows ApiResponse $ref to avoid pruning referenced schemas,Bug Fix,Annotation Processing; SpecFilter,High,4,kuntal1461,2025-09-28T09:04:37Z,https://github.com/swagger-api/swagger-core/pull/4977 +4974,feat: allow empty string as defaultValue in @Schema,Feature,Annotation Processing; Validation,High,4,juntae6942,2025-09-18T06:11:07Z,https://github.com/swagger-api/swagger-core/pull/4974 +4962,MCP Server Opsera,Other,Other,High,4,balamuralipopsera,2025-08-21T13:43:31Z,https://github.com/swagger-api/swagger-core/pull/4962 +4961,MCP Server for Swagger Core,Other,Other,High,4,Vishnu-Opsera,2025-08-21T09:29:58Z,https://github.com/swagger-api/swagger-core/pull/4961 +4954,fix: Java Byte to OAS integer data type,Bug Fix,Annotation Processing; OAS 3.1,High,4,JongminChung,2025-08-14T16:02:31Z,https://github.com/swagger-api/swagger-core/pull/4954 +4861,Added ability to set name for ApiResponse and RequestBody annotations,Other,Annotation Processing; Validation,Medium,3,altro3,2025-03-13T06:52:53Z,https://github.com/swagger-api/swagger-core/pull/4861 +4821,Add DurationSchema for java.time.Duration as PrimitiveType,Other,Other,Medium,3,MoellJ,2025-01-09T11:50:06Z,https://github.com/swagger-api/swagger-core/pull/4821