Skip to content

refactor(dart): align enum description field name with the DefaultCodegen #24506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wing328 merged 1 commit into from
Jul 29, 2026
Merged

refactor(dart): align enum description field name with the DefaultCodegen #24506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions ...enapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractDartCodegen.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@

import static org.openapitools.codegen.CodegenConstants.*;
import static org.openapitools.codegen.utils.CamelizeOption.LOWERCASE_FIRST_LETTER;
import static org.openapitools.codegen.utils.EnumUtils.BUNGIE_X_ENUM_VALUES;
import static org.openapitools.codegen.utils.EnumUtils.getBungieEnumValues;
import static org.openapitools.codegen.utils.StringUtils.*;

public abstract class AbstractDartCodegen extends DefaultCodegen {
Expand Down Expand Up @@ -852,21 +854,19 @@ private List<Map<String, String>> prioritizeContentTypes(List<Map<String, String

@Override
protected void updateEnumVarsWithExtensions(List<Map<String, Object>> enumVars, Map<String, Object> vendorExtensions, String dataType) {
if (vendorExtensions != null && useEnumExtension && vendorExtensions.containsKey("x-enum-values")) {
if (vendorExtensions != null && useEnumExtension && vendorExtensions.containsKey(BUNGIE_X_ENUM_VALUES)) {
// Use the x-enum-values extension for this enum
// Existing enumVars added by the default handling need to be removed first
enumVars.clear();

Object extension = vendorExtensions.get("x-enum-values");
List<Map<String, Object>> values = (List<Map<String, Object>>) extension;
for (Map<String, Object> value : values) {
Map<String, Object> enumVar = new HashMap<>();
enumVar.put(ENUM_NAME, toEnumVarName((String) value.get("identifier"), dataType));
enumVar.put(ENUM_VALUE, toEnumValue(value.get("numericValue").toString(), dataType));
enumVar.put(ENUM_IS_STRING, isDataTypeString(dataType));
if (value.containsKey("description")) {
enumVar.put("description", value.get("description").toString());
}
List<Map<String, String>> bungieEnumValues = getBungieEnumValues((List<Map<String, Object>>) vendorExtensions.get(BUNGIE_X_ENUM_VALUES));

boolean isString = isDataTypeString(dataType);
for (Map<String, String> value : bungieEnumValues) {
Map<String, Object> enumVar = new HashMap<>(value);
enumVar.put(ENUM_NAME, toEnumVarName(value.get(ENUM_NAME), dataType));
enumVar.put(ENUM_VALUE, toEnumValue(value.get(ENUM_VALUE), dataType));
enumVar.put(ENUM_IS_STRING, isString);
enumVars.add(enumVar);
}
} else {
Expand Down
29 changes: 29 additions & 0 deletions modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/EnumUtils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@

public class EnumUtils {

public static final String BUNGIE_X_ENUM_VALUES = "x-enum-values";
private static final String BUNGIE_ENUM_DESCRIPTION = "description";
private static final String BUNGIE_ENUM_IDENTIFIER = "identifier";
private static final String BUNGIE_ENUM_NUMERIC_VALUE = "numericValue";

public static final String ONE_OF = "oneOf";
public static final String ANY_OF = "anyOf";

Expand Down Expand Up @@ -76,6 +81,30 @@ public static List<String> getEnumValuesAsString(Map<String, Object> allowableVa
return enumValues;
}

/**
* Bungie has defined their own enum extension to describe enum values.
* See <a href="https://github.com/Bungie-net/api?tab=readme-ov-file">documentation</a> and the section with
* {@code x-enum-values} for more information.
*
* @param xEnumValues The {@code x-enum-values} Bungie extension map
* @return A list of {@code enumVars} extracted from the {@code x-enum-values} extension
*/
public static List<Map<String, String>> getBungieEnumValues(List<Map<String, Object>> xEnumValues) {
List<Map<String, String>> enumVars = new ArrayList<>();
for (Map<String, Object> enumValue : xEnumValues) {
Map<String, String> enumVar = new HashMap<>();
enumVar.put(ENUM_NAME, (String) enumValue.get(BUNGIE_ENUM_IDENTIFIER));
if (enumValue.containsKey(BUNGIE_ENUM_NUMERIC_VALUE) && enumValue.get(BUNGIE_ENUM_NUMERIC_VALUE) != null) {
enumVar.put(ENUM_VALUE, enumValue.get(BUNGIE_ENUM_NUMERIC_VALUE).toString());
}
if (enumValue.containsKey(BUNGIE_ENUM_DESCRIPTION) && enumValue.get(BUNGIE_ENUM_DESCRIPTION) != null) {
enumVar.put(ENUM_DESCRIPTION, enumValue.get(BUNGIE_ENUM_DESCRIPTION).toString());
}
enumVars.add(enumVar);
}
return enumVars;
}

/**
* Simplifies a composed schema (oneOf/anyOf) where all sub-schemas are enums
* to a single enum schema containing all the values.
Expand Down
7 changes: 5 additions & 2 deletions ...i-generator/src/main/resources/dart/libraries/dio/serialization/built_value/enum.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,19 @@ import 'package:built_value/serializer.dart';

part '{{classFilename}}.g.dart';

{{#description}}
/// {{{description}}}
{{/description}}
{{#isDeprecated}}
@Deprecated('{{{classname}}} has been deprecated')
{{/isDeprecated}}
class {{classname}} extends EnumClass {

{{#allowableValues}}
{{#enumVars}}
{{#description}}
{{#enumDescription}}
/// {{{.}}}
{{/description}}
{{/enumDescription}}
@BuiltValueEnumConst({{#isInteger}}wireNumber: {{{value}}}{{/isInteger}}{{#isLong}}wireNumber: {{{value}}}{{/isLong}}{{^isInteger}}{{^isLong}}wireName: r{{{value}}}{{/isLong}}{{/isInteger}}{{#enumUnknownDefaultCase}}{{#-last}}, fallback: true{{/-last}}{{/enumUnknownDefaultCase}})
static const {{classname}} {{name}} = _${{name}};
{{/enumVars}}
Expand Down
7 changes: 5 additions & 2 deletions ...ator/src/main/resources/dart/libraries/dio/serialization/built_value/enum_inline.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
{{#description}}
/// {{{description}}}
{{/description}}
{{#isDeprecated}}
@Deprecated('{{{enumName}}} has been deprecated')
{{/isDeprecated}}
class {{{enumName}}} extends EnumClass {

{{#allowableValues}}
{{#enumVars}}
{{#description}}
{{#enumDescription}}
/// {{{.}}}
{{/description}}
{{/enumDescription}}
@BuiltValueEnumConst({{#isInteger}}wireNumber: {{{value}}}{{/isInteger}}{{#isLong}}wireNumber: {{{value}}}{{/isLong}}{{^isInteger}}{{^isLong}}wireName: r{{{value}}}{{/isLong}}{{/isInteger}}{{#enumUnknownDefaultCase}}{{#-last}}, fallback: true{{/-last}}{{/enumUnknownDefaultCase}})
static const {{{enumName}}} {{name}} = _${{#lambda.camelcase}}{{{enumName}}}{{/lambda.camelcase}}_{{name}};
{{/enumVars}}
Expand Down
8 changes: 5 additions & 3 deletions ...rator/src/main/resources/dart/libraries/dio/serialization/json_serializable/enum.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
import 'package:json_annotation/json_annotation.dart';

{{#description}}/// {{{description}}}{{/description}}
{{#description}}
/// {{{description}}}
{{/description}}
{{#isDeprecated}}
@Deprecated('{{{classname}}} has been deprecated')
{{/isDeprecated}}
enum {{{classname}}} {
{{#allowableValues}}
{{#enumVars}}
{{^isNull}}
{{#description}}
{{#enumDescription}}
/// {{{.}}}
{{/description}}
{{/enumDescription}}
@JsonValue({{#isString}}r{{/isString}}{{{value}}})
{{{name}}}({{^isString}}'{{/isString}}{{#isString}}r{{/isString}}{{{value}}}{{^isString}}'{{/isString}}){{^-last}},{{/-last}}{{#-last}};{{/-last}}
{{/isNull}}
Expand Down
8 changes: 5 additions & 3 deletions ...rc/main/resources/dart/libraries/dio/serialization/json_serializable/enum_inline.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
{{#enumName}}
{{#description}}/// {{{description}}}{{/description}}
{{#description}}
/// {{{description}}}
{{/description}}
{{#isDeprecated}}
@Deprecated('{{{enumName}}} has been deprecated')
{{/isDeprecated}}
enum {{{ enumName }}} {
{{#allowableValues}}
{{#enumVars}}
{{^isNull}}
{{#description}}
{{#enumDescription}}
/// {{{.}}}
{{/description}}
{{/enumDescription}}
@JsonValue({{#isString}}r{{/isString}}{{{value}}})
{{{name}}}({{^isString}}'{{/isString}}{{#isString}}r{{/isString}}{{{value}}}{{^isString}}'{{/isString}}){{^-last}},{{/-last}}{{#-last}};{{/-last}}
{{/isNull}}
Expand Down
4 changes: 2 additions & 2 deletions modules/openapi-generator/src/test/java/org/openapitools/codegen/dart/DartModelTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -550,12 +550,12 @@ public void testXEnumValuesExtension() {
Assert.assertEquals(enumVars.get(0).get("name"), "foo");
Assert.assertEquals(enumVars.get(0).get("value"), "1");
Assert.assertEquals(enumVars.get(0).get("isString"), false);
Assert.assertEquals(enumVars.get(0).get("description"), "the foo");
Assert.assertEquals(enumVars.get(0).get("enumDescription"), "the foo");

Assert.assertEquals(enumVars.get(1).get("name"), "bar");
Assert.assertEquals(enumVars.get(1).get("value"), "2");
Assert.assertEquals(enumVars.get(1).get("isString"), false);
Assert.assertEquals(enumVars.get(1).get("description"), "the bar");
Assert.assertEquals(enumVars.get(1).get("enumDescription"), "the bar");
}

// datetime (or primitive type) not yet supported in HTTP request body
Expand Down
5 changes: 1 addition & 4 deletions samples/openapi3/client/petstore/dart-dio/petstore-timemachine/lib/src/model/order.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,18 +207,15 @@ class _$OrderSerializer implements PrimitiveSerializer<Order> {
}
}

/// Order Status
class OrderStatusEnum extends EnumClass {

/// Order Status
@BuiltValueEnumConst(wireName: r'placed')
static const OrderStatusEnum placed = _$orderStatusEnum_placed;
/// Order Status
@BuiltValueEnumConst(wireName: r'approved')
static const OrderStatusEnum approved = _$orderStatusEnum_approved;
/// Order Status
@BuiltValueEnumConst(wireName: r'delivered')
static const OrderStatusEnum delivered = _$orderStatusEnum_delivered;
/// Order Status
@BuiltValueEnumConst(wireName: r'unknown_default_open_api', fallback: true)
static const OrderStatusEnum unknownDefaultOpenApi = _$orderStatusEnum_unknownDefaultOpenApi;

Expand Down
5 changes: 1 addition & 4 deletions samples/openapi3/client/petstore/dart-dio/petstore-timemachine/lib/src/model/pet.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,18 +202,15 @@ class _$PetSerializer implements PrimitiveSerializer<Pet> {
}
}

/// pet status in the store
class PetStatusEnum extends EnumClass {

/// pet status in the store
@BuiltValueEnumConst(wireName: r'available')
static const PetStatusEnum available = _$petStatusEnum_available;
/// pet status in the store
@BuiltValueEnumConst(wireName: r'pending')
static const PetStatusEnum pending = _$petStatusEnum_pending;
/// pet status in the store
@BuiltValueEnumConst(wireName: r'sold')
static const PetStatusEnum sold = _$petStatusEnum_sold;
/// pet status in the store
@BuiltValueEnumConst(wireName: r'unknown_default_open_api', fallback: true)
static const PetStatusEnum unknownDefaultOpenApi = _$petStatusEnum_unknownDefaultOpenApi;

Expand Down
2 changes: 0 additions & 2 deletions ...tstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/enum_arrays.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,6 @@ class EnumArrays {

}


enum EnumArraysJustSymbolEnum {
@JsonValue(r'>=')
greaterThanEqual(r'>='),
Expand All @@ -92,7 +91,6 @@ String toString() => value;
}



enum EnumArraysArrayEnumEnum {
@JsonValue(r'fish')
fish(r'fish'),
Expand Down
4 changes: 0 additions & 4 deletions ...petstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/enum_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,6 @@ class EnumTest {

}


enum EnumTestEnumStringEnum {
@JsonValue(r'UPPER')
UPPER(r'UPPER'),
Expand All @@ -200,7 +199,6 @@ String toString() => value;
}



enum EnumTestEnumStringRequiredEnum {
@JsonValue(r'UPPER')
UPPER(r'UPPER'),
Expand All @@ -220,7 +218,6 @@ String toString() => value;
}



enum EnumTestEnumIntegerEnum {
@JsonValue(1)
number1('1'),
Expand All @@ -238,7 +235,6 @@ String toString() => value;
}



enum EnumTestEnumNumberEnum {
@JsonValue('1.1')
number1Period1(''1.1''),
Expand Down
1 change: 0 additions & 1 deletion .../petstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/map_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,6 @@ class MapTest {

}


enum MapTestMapOfEnumStringEnum {
@JsonValue(r'UPPER')
UPPER(r'UPPER'),
Expand Down
1 change: 0 additions & 1 deletion ...e/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/model_enum_class.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum ModelEnumClass {
@JsonValue(r'_abc')
abc(r'_abc'),
Expand Down
1 change: 0 additions & 1 deletion ...re_client_lib_fake-json_serializable/lib/src/model/object_with_duplicate_inline_enum.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,6 @@ class ObjectWithDuplicateInlineEnum {

}


enum ObjectWithDuplicateInlineEnumAttributeEnum {
@JsonValue(r'value_one')
valueOne(r'value_one'),
Expand Down
1 change: 0 additions & 1 deletion ...dio/petstore_client_lib_fake-json_serializable/lib/src/model/object_with_inline_enum.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,6 @@ class ObjectWithInlineEnum {

}


enum ObjectWithInlineEnumAttributeEnum {
@JsonValue(r'value_one')
valueOne(r'value_one'),
Expand Down
3 changes: 0 additions & 3 deletions ...lient_lib_fake-json_serializable/lib/src/model/object_with_inline_enum_default_value.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,13 +60,10 @@ class ObjectWithInlineEnumDefaultValue {

/// Object one attribute enum with default value
enum ObjectWithInlineEnumDefaultValueAttributeEnum {
/// Object one attribute enum with default value
@JsonValue(r'value_one')
valueOne(r'value_one'),
/// Object one attribute enum with default value
@JsonValue(r'value_two')
valueTwo(r'value_two'),
/// Object one attribute enum with default value
@JsonValue(r'unknown_default_open_api')
unknownDefaultOpenApi(r'unknown_default_open_api');

Expand Down
4 changes: 0 additions & 4 deletions ...ent/petstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/order.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,16 +140,12 @@ class Order {

/// Order Status
enum OrderStatusEnum {
/// Order Status
@JsonValue(r'placed')
placed(r'placed'),
/// Order Status
@JsonValue(r'approved')
approved(r'approved'),
/// Order Status
@JsonValue(r'delivered')
delivered(r'delivered'),
/// Order Status
@JsonValue(r'unknown_default_open_api')
unknownDefaultOpenApi(r'unknown_default_open_api');

Expand Down
1 change: 0 additions & 1 deletion ...etstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/outer_enum.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum OuterEnum {
@JsonValue(r'placed')
placed(r'placed'),
Expand Down
1 change: 0 additions & 1 deletion ...io/petstore_client_lib_fake-json_serializable/lib/src/model/outer_enum_default_value.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum OuterEnumDefaultValue {
@JsonValue(r'placed')
placed(r'placed'),
Expand Down
1 change: 0 additions & 1 deletion ...dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/outer_enum_integer.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum OuterEnumInteger {
@JsonValue(0)
number0('0'),
Expand Down
1 change: 0 additions & 1 deletion ...ore_client_lib_fake-json_serializable/lib/src/model/outer_enum_integer_default_value.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum OuterEnumIntegerDefaultValue {
@JsonValue(0)
number0('0'),
Expand Down
4 changes: 0 additions & 4 deletions ...lient/petstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/pet.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,16 +142,12 @@ class Pet {

/// pet status in the store
enum PetStatusEnum {
/// pet status in the store
@JsonValue(r'available')
available(r'available'),
/// pet status in the store
@JsonValue(r'pending')
pending(r'pending'),
/// pet status in the store
@JsonValue(r'sold')
sold(r'sold'),
/// pet status in the store
@JsonValue(r'unknown_default_open_api')
unknownDefaultOpenApi(r'unknown_default_open_api');

Expand Down
1 change: 0 additions & 1 deletion ...re/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/single_ref_type.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum SingleRefType {
@JsonValue(r'admin')
admin(r'admin'),
Expand Down
1 change: 0 additions & 1 deletion ...petstore/dart-dio/petstore_client_lib_fake-json_serializable/lib/src/model/test_enum.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
// ignore_for_file: unused_element
import 'package:json_annotation/json_annotation.dart';


enum TestEnum {
@JsonValue(r'')
empty(r''),
Expand Down
Loading
Loading