0
# Core Generation
1

2
The core generation system provides the fundamental interfaces and implementations for OpenAPI code generation. It defines contracts for customization and executes the generation workflow.
3

4
## Core Interfaces
5

6
### CodegenConfig Interface
7

8
The main interface that defines how code generation is configured and customized for specific languages and frameworks.
9

10
```java { .api }
11
interface CodegenConfig {
12
    // Generator identification
13
    String getName();
14
    String getHelp();
15
    CodegenType getTag();
16
    GeneratorLanguage generatorLanguage();
17
    GeneratorMetadata getGeneratorMetadata();
18
    
19
    // Configuration properties
20
    Map<String, Object> additionalProperties();
21
    Map<String, String> serverVariableOverrides();
22
    Map<String, Object> vendorExtensions();
23
    List<CliOption> cliOptions();
24
    
25
    // Directory and package configuration
26
    String outputFolder();
27
    String templateDir();
28
    String embeddedTemplateDir();
29
    String apiPackage();
30
    String modelPackage();
31
    String apiFileFolder();
32
    String modelFileFolder();
33
    
34
    // Name transformation methods
35
    String toApiName(String name);
36
    String toModelName(String name);
37
    String toParamName(String name);
38
    String escapeText(String text);
39
    String escapeReservedWord(String name);
40
    String sanitizeName(String name);
41
    
42
    // Type handling
43
    String getTypeDeclaration(Schema schema);
44
    String getTypeDeclaration(String name);
45
    
46
    // Model and operation conversion
47
    CodegenModel fromModel(String name, Schema schema);
48
    CodegenOperation fromOperation(String resourcePath, String httpMethod, 
49
                                   Operation operation, List<Server> servers);
50
    
51
    // Processing lifecycle
52
    void processOpts();
53
    void preprocessOpenAPI(OpenAPI openAPI);
54
    void processOpenAPI(OpenAPI openAPI);
55
    
56
    // Post-processing
57
    Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs);
58
    OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<ModelMap> allModels);
59
    
60
    // Template and file handling
61
    List<SupportingFile> supportingFiles();
62
    Map<String, String> apiTemplateFiles();
63
    Map<String, String> modelTemplateFiles();
64
    boolean shouldOverwrite(String filename);
65
    
66
    // Mapping configurations
67
    Map<String, String> typeMapping();
68
    Map<String, String> importMapping();
69
    Map<String, String> schemaMapping();
70
    Map<String, String> nameMapping();
71
    Set<String> reservedWords();
72
}
73
```
74

75
### Generator Interface
76

77
Simple interface for executing the code generation process.
78

79
```java { .api }
80
interface Generator {
81
    Generator opts(ClientOptInput opts);
82
    List<File> generate();
83
}
84
```
85

86
## Default Implementations
87

88
### DefaultCodegen Abstract Class
89

90
Base implementation providing common functionality for all code generators.
91

92
```java { .api }
93
abstract class DefaultCodegen implements CodegenConfig {
94
    // Constructor
95
    public DefaultCodegen();
96
    
97
    // Configuration
98
    public List<CliOption> cliOptions();
99
    public void processOpts();
100
    public void setOpenAPI(OpenAPI openAPI);
101
    
102
    // Model processing
103
    public CodegenModel fromModel(String name, Schema schema);
104
    public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs);
105
    public ModelsMap postProcessModels(ModelsMap objs);
106
    public Map<String, CodegenModel> getAllModels(Map<String, ModelsMap> objs);
107
    
108
    // Operation processing
109
    public CodegenOperation fromOperation(String resourcePath, String httpMethod, 
110
                                          Operation operation, List<Server> servers);
111
    public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<ModelMap> allModels);
112
    
113
    // Name transformation
114
    public String toModelName(String name);
115
    public String toApiName(String name);
116
    public String sanitizeName(String name);
117
    public String escapeText(String text);
118
    public String escapeReservedWord(String name);
119
    
120
    // Enum handling
121
    public String toEnumValue(String value, String datatype);
122
    public String toEnumVarName(String value, String datatype);
123
    public String toEnumDefaultValue(String value, String datatype);
124
    
125
    // Type handling
126
    public String getTypeDeclaration(Schema schema);
127
    public String getSchemaType(Schema schema);
128
    
129
    // Utilities
130
    public boolean specVersionGreaterThanOrEqualTo310(OpenAPI openAPI);
131
    public void postProcess();
132
}
133
```
134

135
### DefaultGenerator Class
136

137
Default implementation of the Generator interface that orchestrates the generation process.
138

139
```java { .api }
140
class DefaultGenerator implements Generator {
141
    // Constructors
142
    public DefaultGenerator();
143
    public DefaultGenerator(Boolean dryRun);
144
    
145
    // Core generation
146
    public Generator opts(ClientOptInput opts);
147
    public List<File> generate();
148
    
149
    // Processing methods
150
    public Map<String, List<CodegenOperation>> processPaths(Paths paths);
151
    public Map<String, List<CodegenOperation>> processWebhooks(Map<String, PathItem> webhooks);
152
    
153
    // Configuration
154
    public void setGenerateMetadata(Boolean generateMetadata);
155
    public void setGeneratorPropertyDefault(final String key, final String value);
156
}
157
```
158

159
## Usage Examples
160

161
### Creating a Custom Generator
162

163
```java
164
// Extend DefaultCodegen for language-specific implementation
165
public class MyCustomGenerator extends DefaultCodegen implements CodegenConfig {
166
    
167
    public MyCustomGenerator() {
168
        super();
169
        
170
        // Configure language-specific settings
171
        outputFolder = "generated-code";
172
        modelTemplateFiles.put("model.mustache", ".java");
173
        apiTemplateFiles.put("api.mustache", ".java");
174
        
175
        // Set up type mappings
176
        typeMapping.put("integer", "Integer");
177
        typeMapping.put("long", "Long");
178
        typeMapping.put("string", "String");
179
    }
180
    
181
    @Override
182
    public String getName() {
183
        return "my-custom-generator";
184
    }
185
    
186
    @Override
187
    public String getHelp() {
188
        return "Generates My Custom language client library.";
189
    }
190
    
191
    @Override
192
    public CodegenType getTag() {
193
        return CodegenType.CLIENT;
194
    }
195
    
196
    // Override methods to customize behavior
197
    @Override
198
    public String toModelName(String name) {
199
        // Custom model name transformation
200
        return camelize(sanitizeName(name));
201
    }
202
}
203
```
204

205
### Executing Generation
206

207
```java
208
// Using DefaultGenerator with configuration
209
CodegenConfigurator configurator = new CodegenConfigurator()
210
    .setGeneratorName("java")
211
    .setInputSpec("openapi.yaml")
212
    .setOutputDir("./generated")
213
    .setApiPackage("com.example.api")
214
    .setModelPackage("com.example.model");
215

216
DefaultGenerator generator = new DefaultGenerator();
217
List<File> generatedFiles = generator.opts(configurator.toClientOptInput()).generate();
218

219
// Process generated files
220
for (File file : generatedFiles) {
221
    System.out.println("Generated: " + file.getAbsolutePath());
222
}
223
```
224

225
### Custom Post-Processing
226

227
```java
228
public class CustomPostProcessingGenerator extends DefaultCodegen {
229
    
230
    @Override
231
    public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
232
        // Apply custom transformations to all models
233
        Map<String, ModelsMap> result = super.postProcessAllModels(objs);
234
        
235
        for (ModelsMap models : result.values()) {
236
            for (ModelMap model : models.getModels()) {
237
                CodegenModel codegenModel = (CodegenModel) model.get("model");
238
                
239
                // Add custom properties or modify model
240
                codegenModel.vendorExtensions.put("x-custom-annotation", true);
241
            }
242
        }
243
        
244
        return result;
245
    }
246
    
247
    @Override
248
    public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<ModelMap> allModels) {
249
        OperationsMap result = super.postProcessOperationsWithModels(objs, allModels);
250
        
251
        // Customize operations
252
        OperationMap operations = result.getOperations();
253
        for (CodegenOperation operation : (List<CodegenOperation>) operations.get("operation")) {
254
            // Add custom operation properties
255
            operation.vendorExtensions.put("x-custom-header", "MyHeader");
256
        }
257
        
258
        return result;
259
    }
260
}
261
```
262

263
## Supporting Classes
264

265
### SupportingFile
266

267
Represents additional files to be generated alongside API and model files.
268

269
```java { .api }
270
class SupportingFile extends TemplateDefinition {
271
    // Constructors
272
    public SupportingFile(String templateFile, String destinationFilename);
273
    public SupportingFile(String templateFile, String folder, String destinationFilename);
274
    
275
    // Configuration
276
    public SupportingFile templateFile(String templateFile);
277
    public SupportingFile folder(String folder);
278
    public SupportingFile destinationFilename(String destinationFilename);
279
    
280
    // Getters
281
    public String getTemplateFile();
282
    public String getFolder();
283
    public String getDestinationFilename();
284
}
285
```
286

287
### VendorExtension
288

289
Configuration for vendor extensions (x-* properties).
290

291
```java { .api }
292
class VendorExtension {
293
    public String name;              // Extension name (e.g., "x-my-extension")
294
    public String description;       // Human-readable description
295
    public String type;             // Data type (string, boolean, etc.)
296
    public Object defaultValue;     // Default value
297
    public List<String> enumValues; // Allowed values for enum types
298
}
299
```