Skip to content

Commit 8133639

Browse files
constewart9constewart9
committed
fix: updated README
1 parent 342cbb4 commit 8133639

File tree

1 file changed

+191
-37
lines changed

1 file changed

+191
-37
lines changed

‎types/codegen/README.md‎

Lines changed: 191 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,205 @@
1-
# Code Generation
1+
# OpenAPI Code Generation
22

3-
This directory contains OpenAPI code generation configuration and post-processing scripts for language server runtime types.
3+
This directory contains scripts and configuration for generating TypeScript and Java types from OpenAPI schema definitions using OpenAPI Generator CLI.
44

5-
## Structure
5+
## Overview
66

7-
- `schema/` - OpenAPI schema definitions
8-
- `custom-templates/` - Custom Mustache templates for code generation sorted by langauage
9-
- `generated/` - Generated output directory where TypeScript and Java types will be located post generation
10-
- `post-generate.js` - Post-processing script
11-
- `openapitools.json` - OpenAPI Generator configuration
7+
The code generation process combines multiple schema files into a complete OpenAPI specification and generates both TypeScript and Java types with custom templates, import mappings, and validation.
8+
9+
**Running `npm run generate` will automatically generate:**
10+
- **TypeScript types** in `generated/typescript/` - Complete type definitions and runtime client
11+
- **Java model classes** in `generated/java/` - Filtered model classes for specific use cases
12+
13+
## Directory Structure
14+
15+
```
16+
types/codegen/
17+
├── schema/ # Schema definition files
18+
│ ├── chatTypes.json # Main schema definitions
19+
│ └── complete-schema.json # Generated complete OpenAPI spec
20+
├── scripts/ # Generation and validation scripts
21+
│ ├── generate-complete-schema.js # Combines all schema files
22+
│ ├── post-typescript.js # TypeScript post-processing
23+
│ ├── post-test.js # Model validation script
24+
│ ├── pre-typescript.js # TypeScript pre-processing
25+
│ └── constants.ts # Constants to inject
26+
├── custom-templates/ # Custom Mustache templates
27+
│ ├── typescript/ # TypeScript-specific templates
28+
│ └── java/ # Java-specific templates
29+
├── generated/ # Generated output files
30+
│ ├── typescript/ # TypeScript types
31+
│ └── java/ # Java model classes
32+
├── tests/ # Test schemas and validation
33+
└── openapitools.json # Generator configuration
34+
```
35+
36+
## Process Flow
37+
38+
### 1. Schema Generation (`generate-complete-schema.js`)
39+
- Scans all JSON files in the `schema/` directory
40+
- Combines schemas from multiple files into a single collection
41+
- Creates `complete-schema.json` with complete OpenAPI 3.0.0 structure:
42+
- Dynamic version from `openapitools.json` TypeScript generator config
43+
- Combined schemas from all source files
44+
- Proper OpenAPI structure and formatting
45+
- Conflict detection and warnings for duplicate schema names
46+
47+
### 2. Code Generation (OpenAPI Generator CLI)
48+
- **TypeScript Generator**: Generates complete TypeScript types and runtime
49+
- Uses `typescript-fetch` generator with custom templates
50+
- Generates interfaces, types, and enum unions
51+
- Includes runtime API client code
52+
- **Java Generator**: Generates filtered Java model classes
53+
- Uses selective model generation via `global-property.models`
54+
- Only generates specific models needed for Java integration
55+
- Targets Java 21 with modern features
56+
57+
### 3. Post-Processing (`post-typescript.js`)
58+
- Processes import mappings from `openapitools.json`
59+
- Adds external library imports (e.g., `vscode-languageserver-types`)
60+
- Injects constants from `constants.ts`
61+
- Modifies interface visibility (e.g., makes `PartialResultParams` internal)
62+
63+
### 4. Validation (`post-test.js`)
64+
- Validates generated models against schema definitions
65+
- Checks for missing models (should be generated but aren't)
66+
- Reports extra/intermediate models (generated but not in schema)
67+
- Supports verbose mode for detailed analysis
68+
- Respects `global-property.models` filters for accurate validation
69+
70+
## Available Scripts
71+
72+
```bash
73+
# Generate complete schema from individual files
74+
npm run generate-schema
75+
76+
# Full generation pipeline (schema + generation + post-processing + validation)
77+
npm run generate
78+
79+
# Generation without post-processing
80+
npm run generate:no-post
81+
82+
# Validate generated models (errors only)
83+
npm run test
84+
npm run validate
85+
86+
# Validate with detailed output (includes extra/intermediate models)
87+
npm run test:verbose
88+
```
1289

1390
## Configuration
1491

15-
### openapitools.json
92+
### Generator Configuration (`openapitools.json`)
93+
94+
The main configuration file contains detailed settings for both TypeScript and Java generators:
95+
96+
#### TypeScript Generator Settings
97+
- **Generator**: `typescript-fetch` - Generates TypeScript types with fetch-based runtime
98+
- **ES6 Support**: `supportsES6: true` - Modern JavaScript features
99+
- **Property Naming**: `camelCase` for both models and enums
100+
- **String Enums**: `stringEnums: true` - Generates union types instead of numeric enums
101+
- **Runtime Checks**: `withoutRuntimeChecks: true` - Lighter generated code
102+
- **Additional Properties**: `nullSafeAdditionalProps: false` - Flexible object handling
103+
- **OpenAPI Normalizer**: `REF_AS_PARENT_IN_ALLOF: true` - Better inheritance handling
104+
105+
#### Java Generator Settings
106+
- **Generator**: `java` - Standard Java model classes
107+
- **Java Version**: Source and target compatibility set to Java 21
108+
- **OneOf Interfaces**: `useOneOfInterfaces: true` - Union type handling using interfaces
109+
- **Date Library**: `java8` - Uses modern Java time APIs
110+
- **Validation**: Bean validation disabled for lighter models
111+
- **Legacy Behavior**: `legacyDiscriminatorBehavior: false` - Modern discriminator handling
112+
113+
### Model Filtering
114+
115+
Java generator uses selective model generation via `global-property.models`:
116+
```json
117+
"global-property": {
118+
"models": "IconType:ContextCommandGroup:QuickActionCommand:ContextCommand:CursorPosition:FileParams:CopyFileParams:OpenFileDiffParams:ShowOpenDialogParams:ShowSaveFileDialogParams:ShowSaveFileDialogResult"
119+
}
120+
```
121+
122+
This generates only the specified models, making the Java output focused on specific use cases.
123+
124+
### Import Mappings
125+
126+
Both generators support external type imports, but handle them differently:
127+
128+
#### Java Import Mappings
129+
```json
130+
"importMappings": {
131+
"Position": "org.eclipse.lsp4j.Position",
132+
"Range": "org.eclipse.lsp4j.Range",
133+
"TextDocumentIdentifier": "org.eclipse.lsp4j.TextDocumentIdentifier"
134+
}
135+
```
136+
137+
#### TypeScript Import Mappings
138+
Handled by `post-typescript.js` for more flexible processing:
139+
```json
140+
"importMappings": {
141+
"Position": "vscode-languageserver-types",
142+
"Range": "vscode-languageserver-types",
143+
"TextDocumentIdentifier": "vscode-languageserver-types"
144+
}
145+
```
146+
147+
### Type Mappings
148+
149+
Custom type mappings for language-specific types:
150+
151+
#### Java Type Mappings
152+
```json
153+
"typeMappings": {
154+
"IconType": "String",
155+
"Uint8Array": "byte[]"
156+
}
157+
```
158+
159+
#### TypeScript Type Mappings
160+
```json
161+
"typeMappings": {
162+
"Date": "Date"
163+
}
164+
```
165+
166+
### Reserved Words
16167

17-
OpenAPI Generator configuration defining code generation settings for TypeScript and Java:
168+
Handle language-specific reserved words:
169+
```json
170+
"reservedWordsMappings": {
171+
"export": "export"
172+
}
173+
```
18174

19-
**Common Configuration:**
20-
- `generatorName` - Specifies the generator type (typescript-fetch, java)
21-
- `disabled` - Allows selective turning off of generators during development. By default, all generators run. New languages/input specs can be added with their own customization
22-
- `output` - Target directory for generated code
23-
- `inputSpec` - Source OpenAPI schema file
24-
- `templateDir` - Points to custom Mustache templates that overwrite canonical templates from [OpenAPI Generator templates](https://openapi-generator.tech/docs/templating)
175+
## Output
25176

26-
**TypeScript Configuration:**
27-
- `additionalProperties` - Language-specific options from the [typescript-fetch generator](https://openapi-generator.tech/docs/generators/typescript-fetch/). Notable settings:
28-
- `stringEnums` - Generates string enums instead of numeric
29-
- `withoutRuntimeChecks` - Reduces unnecessary generated code by removing runtime validation
30-
- `supportsES6` - Enables ES6 features
31-
- `modelPropertyNaming`/`enumPropertyNaming` - Sets camelCase naming conventions
32-
- `global-property` - [Global properties](https://openapi-generator.tech/docs/globals) for debugging and selective model generation (alternative to .openapi-generator-ignore file)
33-
- `openapi-normalizer` - [Normalizers](https://openapi-generator.tech/docs/customization/#openapi-normalizer) shape input before generation:
34-
- `REF_AS_PARENT_IN_ALLOF` - Enables traditional inheritance (extends) via allOf instead of including all parent fields in child, resulting in cleaner code
35-
- `reservedWordsMappings` - Overcomes generator renaming of reserved words. Forces `export` field to remain `export` instead of being renamed to `_export`
36-
- `typeMappings` - Overcomes generator quirks where `Date` gets converted to `string` or `ModelDate`. Forces generator to use proper `Date` type
177+
### TypeScript Output (`generated/typescript/`)
178+
- Complete type definitions for all schema models
179+
- Runtime API client with fetch-based implementation
180+
- Proper import statements for external dependencies
181+
- Injected constants and utilities
182+
- NPM package ready for distribution
37183

38-
**Java Configuration:** TODO TODO TODO
39-
- `additionalProperties` - Java-specific settings including Java 21 compatibility, validation options, and serialization settings
40-
- `global-property.models` - Specifies exact models to generate (CursorPosition, FileParams, etc.) for selective generation
41-
- `importMappings` - Maps external types to LSP4J classes for seamless integration with Language Server Protocol
184+
### Java Output (`generated/java/`)
185+
- Selective model classes (only specified models via filtering)
186+
- Java 21 compatible code
187+
- LSP4J integration for language server types
188+
- Maven/Gradle compatible structure
42189

43-
## Post-Processing
190+
## Validation Results
44191

45-
The `post-generate.js` script runs after OpenAPI code generation to customize the generated TypeScript types:
192+
The validation script provides detailed reporting:
193+
- **Schema models**: Total models defined in schema files
194+
- **TypeScript models**: Generated models (includes intermediate models)
195+
- **Java models**: Generated models (filtered subset based on configuration)
196+
- **Missing models**: Models that should be generated but aren't
197+
- **Extra models**: Intermediate models created by OpenAPI generator
46198

47-
- **Adds constants**: Adds protocol method constants from `constants.ts` to the generated index file. This is due to a limitation of the OpenAPI generator which ignores type alias constants in generation.
48-
- **Modifies interfaces**: Changes `PartialResultParams` from exported to internal interface. This is because `PartialResultParams` is only used internally and causes conflicts with VS Code LSP protocol type of the same name if exported. This interface is not exported in the current `chat.ts` either.
49-
- **Extensible**: Other post-processing steps should be added here.
199+
## Development Workflow
50200

51-
This ensures the generated types integrate properly with the language server runtime while maintaining clean separation between generated and hand-written code.
201+
1. **Add/modify schemas** in `schema/chatTypes.json`
202+
2. **Run generation**: `npm run generate`
203+
3. **Review validation**: Check for missing or extra models
204+
4. **Test integration**: Use generated types in your application
205+
5. **Commit changes**: Only commit schema files, not generated files

0 commit comments

Comments
 (0)