0
# OpenAPI Generator
1

2
OpenAPI Generator is a comprehensive code generation framework that automatically creates API client libraries, server stubs, documentation, and configuration files from OpenAPI Specification documents (versions 2.0 and 3.0). It provides extensive customization through templates and configuration, supporting over 50 programming languages and frameworks.
3

4
## Package Information
5

6
- **Package Name**: openapi-generator
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.openapitools</groupId><artifactId>openapi-generator</artifactId><version>7.14.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import org.openapitools.codegen.*;
15
import org.openapitools.codegen.config.CodegenConfigurator;
16
```
17

18
## Basic Usage
19

20
```java
21
import org.openapitools.codegen.DefaultGenerator;
22
import org.openapitools.codegen.config.CodegenConfigurator;
23

24
// Configure the generator
25
CodegenConfigurator configurator = new CodegenConfigurator()
26
    .setGeneratorName("java")
27
    .setInputSpec("https://petstore.swagger.io/v2/swagger.json")
28
    .setOutputDir("./generated-code");
29

30
// Generate the code
31
DefaultGenerator generator = new DefaultGenerator();
32
List<File> files = generator.opts(configurator.toClientOptInput()).generate();
33
```
34

35
## Architecture
36

37
OpenAPI Generator is built around several key components:
38

39
- **CodegenConfig Interface**: Defines the contract for code generation configuration and customization
40
- **Generator Implementation**: Executes the generation process using configured settings
41
- **Model System**: Represents OpenAPI schemas as Java objects for template processing
42
- **Template Engine**: Processes Mustache/Handlebars templates with model data
43
- **Language Generators**: 50+ specific implementations for different programming languages
44
- **Configuration System**: Flexible option handling and customization framework
45

46
## Capabilities
47

48
### Core Code Generation
49

50
Primary interfaces and classes for setting up and executing code generation workflows. Essential for creating custom generators and configuring generation processes.
51

52
```java { .api }
53
interface CodegenConfig {
54
    String getName();
55
    CodegenType getTag();
56
    GeneratorLanguage generatorLanguage();
57
    
58
    // Model and operation conversion
59
    CodegenModel fromModel(String name, Schema schema);
60
    CodegenOperation fromOperation(String resourcePath, String httpMethod, 
61
                                   Operation operation, List<Server> servers);
62
    
63
    // Post-processing
64
    Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs);
65
    OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<ModelMap> allModels);
66
}
67

68
interface Generator {
69
    Generator opts(ClientOptInput opts);
70
    List<File> generate();
71
}
72
```
73

74
[Core Generation](./core-generation.md)
75

76
### Configuration Management
77

78
Configuration classes and builders for setting up generation parameters, including input specifications, output directories, and generator options.
79

80
```java { .api }
81
class CodegenConfigurator {
82
    public static CodegenConfigurator fromFile(String configFile, Module... modules);
83
    
84
    public CodegenConfigurator setGeneratorName(String generatorName);
85
    public CodegenConfigurator setInputSpec(String inputSpec);
86
    public CodegenConfigurator setOutputDir(String outputDir);
87
    public CodegenConfigurator addAdditionalProperty(String key, Object value);
88
    
89
    public ClientOptInput toClientOptInput();
90
}
91

92
class ClientOptInput {
93
    public ClientOptInput openAPI(OpenAPI openAPI);
94
    public ClientOptInput config(CodegenConfig codegenConfig);
95
}
96
```
97

98
[Configuration Management](./configuration.md)
99

100
### Model System
101

102
Classes representing OpenAPI schemas, operations, parameters, and responses as Java objects for template processing and code generation.
103

104
```java { .api }
105
class CodegenModel implements IJsonSchemaValidationProperties {
106
    public String name;              // Schema name
107
    public String classname;         // Generated class name
108
    public String description;       // Model description
109
    public List<CodegenProperty> vars;         // Model properties
110
    public List<CodegenProperty> requiredVars; // Required properties
111
    public String parent;            // Parent class name
112
    public List<String> interfaces;  // Implemented interfaces
113
}
114

115
class CodegenOperation {
116
    public String path;              // URL path
117
    public String operationId;       // Operation identifier
118
    public String httpMethod;        // HTTP method
119
    public String nickname;          // Generated method name
120
    public List<CodegenParameter> allParams;   // All parameters
121
    public List<CodegenResponse> responses;    // Response definitions
122
    public String returnType;        // Return type
123
}
124
```
125

126
[Model System](./model-system.md)
127

128
### Validation Framework
129

130
JSON Schema validation properties and type checking utilities for ensuring proper data handling and constraint validation.
131

132
```java { .api }
133
interface IJsonSchemaValidationProperties {
134
    // Type identification
135
    boolean getIsModel();
136
    boolean getIsArray();
137
    boolean getIsString();
138
    boolean getIsNumber();
139
    
140
    // Validation constraints
141
    String getPattern();
142
    String getMinimum();
143
    String getMaximum();
144
    Integer getMinLength();
145
    Integer getMaxLength();
146
    
147
    // Schema relationships
148
    CodegenProperty getItems();
149
    List<CodegenProperty> getVars();
150
}
151
```
152

153
[Validation Framework](./validation.md)
154

155
### Utility Functions
156

157
Helper classes and utilities for schema analysis, string manipulation, version handling, and model processing.
158

159
```java { .api }
160
class ModelUtils {
161
    public static boolean isObjectSchema(Schema schema);
162
    public static boolean isArraySchema(Schema schema);
163
    public static boolean isStringSchema(Schema schema);
164
    public static List<String> getAllUsedSchemas(OpenAPI openAPI);
165
    public static Schema unaliasSchema(Schema schema, OpenAPI openAPI);
166
}
167

168
class StringUtils {
169
    public static String camelize(String word);
170
    public static String underscore(String word);
171
    public static String dashize(String word);
172
}
173
```
174

175
[Utility Functions](./utilities.md)
176

177
## Common Types
178

179
```java { .api }
180
enum CodegenType {
181
    CLIENT,          // Client library generation
182
    SERVER,          // Server stub generation  
183
    DOCUMENTATION,   // Documentation generation
184
    SCHEMA,          // Schema-only generation
185
    CONFIG,          // Configuration file generation
186
    OTHER            // Other/custom generation types
187
}
188

189
enum GeneratorLanguage {
190
    JAVA, PYTHON, JAVASCRIPT, TYPESCRIPT, C_SHARP, GO, RUBY, PHP, 
191
    SWIFT, KOTLIN, SCALA, C_PLUS_PLUS, RUST, // ... 50+ languages
192
}
193

194
class SpecValidationException extends RuntimeException {
195
    public Set<String> getErrors();
196
    public Set<String> getWarnings();
197
}
198
```