Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions docs/generators/kotlin-spring.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|x-discriminator-value|Used with model inheritance to specify value for discriminator that identifies current model|MODEL|
|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
|x-operation-extra-annotation|Custom annotation(s) to be added to operation; accepts a string or list of strings|OPERATION|null
|x-extra-imports|Custom import(s) to add to the generated file that declares the annotated model, property, operation, or parameter (e.g. so custom annotations can be referenced by their short name); accepts a string or list of strings. Values are emitted verbatim (Kotlin alias imports supported) and only exact duplicates are removed|MODEL, FIELD, OPERATION, OPERATION_PARAMETER|null
|x-pattern-message|Add this property whenever you need to customize the invalidation error message for the regex pattern of a variable|FIELD, OPERATION_PARAMETER|null
|x-size-message|Add this property whenever you need to customize the invalidation error message for the size or length of a variable|FIELD, OPERATION_PARAMETER|null
|x-minimum-message|Add this property whenever you need to customize the invalidation error message for the minimum value of a variable|FIELD, OPERATION_PARAMETER|null
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ public enum VendorExtension {
X_CLASS_EXTRA_ANNOTATION("x-class-extra-annotation", ExtensionLevel.MODEL, "Custom annotation(s) to be added to model; accepts a string or list of strings", null),
X_FIELD_EXTRA_ANNOTATION("x-field-extra-annotation", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Custom annotation(s) to be added to property; accepts a string or list of strings", null),
X_OPERATION_EXTRA_ANNOTATION("x-operation-extra-annotation", ExtensionLevel.OPERATION, "Custom annotation(s) to be added to operation; accepts a string or list of strings", null),
X_EXTRA_IMPORTS("x-extra-imports", Arrays.asList(ExtensionLevel.MODEL, ExtensionLevel.FIELD, ExtensionLevel.OPERATION, ExtensionLevel.OPERATION_PARAMETER), "Custom import(s) to add to the generated file that declares the annotated model, property, operation, or parameter (e.g. so custom annotations can be referenced by their short name); accepts a string or list of strings. Values are emitted verbatim (Kotlin alias imports supported) and only exact duplicates are removed", null),
X_VERSION_PARAM("x-version-param", ExtensionLevel.OPERATION_PARAMETER, "Marker property that tells that this parameter would be used for endpoint versioning. Applicable for headers & query params. true/false", null),
X_PATTERN_MESSAGE("x-pattern-message", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Add this property whenever you need to customize the invalidation error message for the regex pattern of a variable", null),
X_SIZE_MESSAGE("x-size-message", Arrays.asList(ExtensionLevel.FIELD, ExtensionLevel.OPERATION_PARAMETER), "Add this property whenever you need to customize the invalidation error message for the size or length of a variable", null),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1337,6 +1337,79 @@ public void addImportsToOneOfInterface(List<Map<String, String>> imports) {
}
}

/**
* Reads the {@code x-extra-imports} vendor extension from the given vendor-extension map and
* appends its values to {@code target}. The extension accepts either a single string or a list
* of strings; parsing is delegated to {@link #getObjectAsStringList(Object)} for consistency with
* how the sibling {@code x-*-extra-annotation} extensions are handled. Values are preserved
* verbatim (Kotlin alias imports are supported); no validation, trimming, or conflict detection is
* performed. Exact-duplicate handling is left to the caller's collection (typically a
* {@link LinkedHashSet} to keep insertion order while removing duplicates).
*
* @param vendorExtensions vendor extensions of a model, property, operation, or parameter (may be {@code null})
* @param target collection to which extracted import directives are added
*/
private void collectExtraImports(Map<String, Object> vendorExtensions, Collection<String> target) {
if (vendorExtensions == null) {
return;
}
target.addAll(getObjectAsStringList(vendorExtensions.get(VendorExtension.X_EXTRA_IMPORTS.getName())));
}

/**
* Appends the given import directives to an {@code imports}-style list (a list of maps each
* holding a single {@code "import"} entry, as rendered by the {@code {{#imports}}} template
* blocks), skipping directives whose exact text already appears in the list.
*
* @param imports existing import list to extend (must be mutable)
* @param extraImports import directives to add, in insertion order
*/
private void appendExtraImports(List<Map<String, String>> imports, Collection<String> extraImports) {
Set<String> existing = imports.stream()
.map(m -> m.get("import"))
.filter(Objects::nonNull)
.collect(Collectors.toCollection(HashSet::new));
for (String imp : extraImports) {
if (existing.add(imp)) {
Map<String, String> item = new HashMap<>();
item.put("import", imp);
imports.add(item);
}
}
}

@Override
public ModelsMap postProcessModels(ModelsMap objs) {
objs = super.postProcessModels(objs);

// Collect x-extra-imports declared on each model and its properties, and add them to the
// model file's import list so custom class/field annotations can be referenced by short name.
// Each ModelsMap corresponds to a single generated model file, so this stays file-scoped.
Set<String> extraImports = new LinkedHashSet<>();
for (ModelMap mo : objs.getModels()) {
CodegenModel cm = mo.getModel();
if (cm == null) {
continue;
}
collectExtraImports(cm.vendorExtensions, extraImports);
// allVars is the complete property set (own + inherited); vars is included for safety.
// The LinkedHashSet collapses any overlap between the two lists.
Stream.of(cm.vars, cm.allVars)
.filter(Objects::nonNull)
.flatMap(List::stream)
.forEach(p -> collectExtraImports(p.vendorExtensions, extraImports));
}
if (!extraImports.isEmpty()) {
List<Map<String, String>> imports = objs.getImports();
if (imports == null) {
imports = new ArrayList<>();
objs.setImports(imports);
}
appendExtraImports(imports, extraImports);
}
return objs;
}

@Override
public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
objs = super.postProcessAllModels(objs);
Expand Down Expand Up @@ -1689,6 +1762,43 @@ public void setReturnContainer(final String returnContainer) {

handleImplicitHeaders(objs);

// Collect x-extra-imports declared on operations and their parameters for this API group.
// Grouping (by tag or by path segment, per useTags) is already reflected in this OperationsMap,
// so the imports are scoped to exactly the API file(s) that render these operations. They are
// exposed under a dedicated key (not the shared "imports" list) so that only templates which
// render the related annotations (api.mustache / apiInterface.mustache) emit them, while
// delegate, controller-wrapper, service and test templates do not.
if (operations != null) {
Set<String> operationExtraImports = new LinkedHashSet<>();
for (CodegenOperation operation : operations.getOperation()) {
collectExtraImports(operation.vendorExtensions, operationExtraImports);
if (operation.allParams != null) {
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
operation.allParams.forEach(param -> collectExtraImports(param.vendorExtensions, operationExtraImports));
}
// Implicit header params are moved out of allParams by handleImplicitHeaders above,
// so scan them separately to avoid dropping their declared imports.
if (operation.implicitHeadersParams != null) {
operation.implicitHeadersParams.forEach(param -> collectExtraImports(param.vendorExtensions, operationExtraImports));
}
}
// Drop any import already present in the shared imports list (e.g. produced from an
// operation's types) so the file keeps the documented once-per-file deduplication.
Set<String> existingImports = objs.getImports().stream()
.map(m -> m.get("import"))
.filter(Objects::nonNull)
.collect(Collectors.toCollection(HashSet::new));
operationExtraImports.removeAll(existingImports);
if (!operationExtraImports.isEmpty()) {
List<Map<String, String>> extraImportList = new ArrayList<>();
for (String imp : operationExtraImports) {
Map<String, String> item = new HashMap<>();
item.put("import", imp);
extraImportList.add(item);
}
objs.put("operationExtraImports", extraImportList);
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
}
}

return objs;
}

Expand Down Expand Up @@ -1777,6 +1887,7 @@ public List<VendorExtension> getSupportedVendorExtensions() {
extensions.add(VendorExtension.X_DISCRIMINATOR_VALUE);
extensions.add(VendorExtension.X_FIELD_EXTRA_ANNOTATION);
extensions.add(VendorExtension.X_OPERATION_EXTRA_ANNOTATION);
extensions.add(VendorExtension.X_EXTRA_IMPORTS);
extensions.add(VendorExtension.X_PATTERN_MESSAGE);
extensions.add(VendorExtension.X_SIZE_MESSAGE);
extensions.add(VendorExtension.X_MINIMUM_MESSAGE);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@ package {{package}}

{{#imports}}import {{import}}
{{/imports}}
{{#operationExtraImports}}import {{{import}}}
{{/operationExtraImports}}
{{! Dedicated key (not the shared imports list) so these x-extra-imports render only in files that
emit x-operation-extra-annotation. The OperationsMap imports list is shared with apiDelegate,
service, api_test, etc., which don't; keeping them here avoids leaking unused imports there. }}
{{#swagger2AnnotationLibrary}}
import io.swagger.v3.oas.annotations.*
import io.swagger.v3.oas.annotations.enums.*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ package {{package}}

{{#imports}}import {{import}}
{{/imports}}
{{#operationExtraImports}}import {{{import}}}
{{/operationExtraImports}}
{{! Dedicated key (not the shared imports list) so these x-extra-imports render only in files that
emit x-operation-extra-annotation. The OperationsMap imports list is shared with apiDelegate,
service, api_test, etc., which don't; keeping them here avoids leaking unused imports there. }}
{{#swagger2AnnotationLibrary}}
import io.swagger.v3.oas.annotations.*
import io.swagger.v3.oas.annotations.enums.*
Expand Down
Loading
Loading