[RFC] OpenAPI Consumer/API client Module/Codegen

[Evanion]

Overview

Many modern APIs provide OpenAPI (Swagger) specs for their endpoints. While most frameworks focus on generating OpenAPI specs from code, there is a growing need to consume OpenAPI specs and generate type-safe, developer-owned DTOs/entities for use within your application.

For NexusDI, the goal is to provide an OpenAPI consumer/codegen module as a separate package that:

• Consumes OpenAPI specs (local files or remote URLs)
• Generates TypeScript DTOs/entities (classes or interfaces) in the user’s repo
• Allows developers to add decorators for validation, transformation, or ORM mapping (e.g., TypeORM)
• Empowers developers to “own” and customize the generated code, similar to Prisma or shadcn/ui
• Optionally generates type-safe HTTP clients for API consumption

Motivation

• Type safety: All API types are available in the user’s codebase.
• Customizability: Users can add validation, transformation, or ORM decorators to generated DTOs/entities.
• Integration: DTOs/entities can be used across the app (e.g., for validation, persistence, or mapping).
• Developer ownership: Generated code is checked into version control and can be extended or customized as needed.
• No runtime magic: Everything is visible, editable, and under the developer’s control.
• Unified configuration: All codegen and DI-related config can be managed in a single container.json file at the project root.

Proposed Features

• CLI to generate TypeScript DTOs/entities from an OpenAPI spec (local file or remote URL)
• Output code to a user-specified directory (configured in container.json)
• Support for both classes and interfaces (configurable)
• Optionally generate type-safe HTTP clients for API consumption
• Generated code is intended to be checked into the user’s repo and customized
• Support for re-generation with merge/overwrite strategies
• Optionally generate JSDoc comments from OpenAPI descriptions
• Unified project-level config file: container.json for all DI/codegen options

Example Workflow

1. User creates a container.json at the project root:

   {
     "openapi": [
       {
         "name": "product",
         "spec": "https://api.example.com/openapi.yaml",
         "output": "src/api/product",
         "client": true,
         "dtoStyle": "class"
       },
       {
         "name": "user",
         "spec": "./openapi-user.yaml",
         "output": "src/api/user",
         "client": false,
         "dtoStyle": "interface"
       }
     ],
     "http": {
       "defaultTimeout": 5000
     },
     "rbac": {
       "defaultRole": "user"
     }
   }

2. User runs the CLI:

   npx nexusdi-openapi generate
   

   • The CLI reads the OpenAPI section from container.json and generates code for all listed APIs.

3. Generated output:

   • src/api/product/Product.ts
   • src/api/product/ProductList.ts
   • src/api/product/CreateProductDto.ts
   • etc.

4. User customizes DTOs/entities:

   // src/api/product/Product.ts (generated, then customized)
   import { Entity, Column } from 'typeorm';
   import { IsString, IsNumber } from 'class-validator';
   
   @Entity()
   export class Product {
     @Column()
     @IsString()
     name: string;
   
     @Column()
     @IsNumber()
     price: number;
   
     // ...other fields...
   }

5. User can now use these DTOs/entities:

   • In HTTP clients (type-safe API calls)
   • In validation (e.g., with class-validator)
   • In persistence (e.g., with TypeORM)
   • In mapping/transformation logic

Handling Regeneration: Alternatives

When the OpenAPI spec changes and you need to regenerate DTOs/entities, how should we handle user customizations (e.g., decorators, custom methods)? Here are some possible strategies:

1. Overwrite Everything (Simple, but Destructive)

• Every time you regenerate, all generated files are overwritten.
• Downside: Any user-added decorators, comments, or customizations are lost.

2. Base + Extension Pattern (Recommended by Many Tools)

• The generator creates a “base” class or interface (e.g., ProductBase.ts).
• Users create a separate file (e.g., Product.ts) that extends or composes the base.
• The generator never overwrites the user’s custom file.
• Downside: Slightly more boilerplate, but preserves customizations.

3. Code Markers/Regions (Merge-Friendly)

• The generator marks regions in the file as “generated” and leaves space for user code.
• On regeneration, only the marked regions are updated.
• Downside: Can get messy, and not all code editors/tools handle this well.

4. Decorator/Metadata Files

• The generator creates DTOs/entities.
• Users add decorators in a separate metadata file (e.g., Product.decorators.ts).
• At runtime, decorators are applied via reflection or a helper.
• Downside: More complex, less idiomatic for TypeScript.

5. Interactive/Smart Merge Tools

• The generator attempts to merge changes, preserving user customizations.
• Tools like Prisma and some openapi codegens use this approach to some extent.
• Downside: Merge conflicts can still happen, and it’s not foolproof.

Open Questions

• Which regeneration strategy would you prefer? (see above)
• Should the generator support both classes and interfaces, or just one?
• What codegen tool/library should be used (openapi-typescript, openapi-typescript-codegen, etc.)?
• Should the generator also create type-safe HTTP clients, or focus solely on DTOs/entities?
• Should we support both OpenAPI 2.0 and 3.x specs?
• What customization hooks or templates would be most useful for developers?
• Would you prefer a unified container.json for all DI-related config?
• What other features or modules would you want to configure here?

API Sketch

npx nexusdi-openapi generate
# (reads config from container.json)

// src/api/product/Product.ts (generated, then customized)
import { Entity, Column } from 'typeorm';
import { IsString, IsNumber } from 'class-validator';

@Entity()
export class Product {
  @Column()
  @IsString()
  name: string;

  @Column()
  @IsNumber()
  price: number;

  // ...other fields...
}

## Call for Feedback

- Would you use this workflow to integrate external APIs with your app’s validation or ORM layers?
- What codegen features or customization hooks would you want?
- Which regeneration strategy would you prefer, and why?
- Should the generator support both classes and interfaces?
- Any concerns about overwriting or merging changes on re-generation?
- Any preferences for codegen tools or libraries?
- Would you prefer a unified `container.json` for all DI-related config?
- What other features or modules would you want to configure here?
- Any other features or pain points you’d like to see addressed?