🇺🇸 English: Generate all TypeScript DTOs from an OpenAPI/Swagger specification in a single command. Supports OpenAPI 3.x and Swagger 2.x, with automatic spec discovery from documentation pages. 🇪🇸 Español: Genera todos los DTOs TypeScript a partir de una especificación OpenAPI/Swagger en un solo comando. Soporta OpenAPI 3.x y Swagger 2.x, con descubrimiento automático del spec desde páginas de documentación.

ES: El modo --swagger del CLI de Bytekit descarga un spec OpenAPI/Swagger, lee todos los schemas definidos y genera un archivo TypeScript con interfaces y tipos para cada uno. Si le pasas una URL de documentación (Swagger UI), intentará encontrar el JSON del spec automáticamente.

EN: The --swagger mode of the Bytekit CLI downloads an OpenAPI/Swagger spec, reads all defined schemas, and generates a TypeScript file with interfaces and types for each one. If you pass a documentation URL (Swagger UI), it will try to find the spec JSON automatically.

bytekit --swagger https://petstore.swagger.io/v2/swagger.json
# ✅ Successfully generated 6 types!
# 📝 Output: src/types/api-docs.ts

bytekit --swagger <url>

ES: La URL puede ser:

• Un enlace directo al JSON del spec (/swagger.json, /openapi.json)
• Una URL de Swagger UI / documentación (el CLI intentará descubrir el spec)

EN: The URL can be:

• A direct link to the spec JSON (/swagger.json, /openapi.json)
• A Swagger UI / documentation URL (the CLI will try to discover the spec)

⚠️ v3 — HTTPS enforcement / Forzado de HTTPS

EN: Since v3, the CLI rejects remote http:// URLs. Only https:// is allowed for remote hosts. http://localhost and loopback addresses (127.0.0.1, ::1) remain allowed for local development.

ES: Desde v3, el CLI rechaza URLs remotas con http://. Solo se permite https:// para hosts remotos. http://localhost y direcciones de loopback (127.0.0.1, ::1) siguen permitidas para desarrollo local.

# Swagger 2.x
bytekit --swagger https://petstore.swagger.io/v2/swagger.json

# OpenAPI 3.x
bytekit --swagger https://api.example.com/openapi.json

# Swagger UI page — auto-discovers the JSON spec
bytekit --swagger https://petstore.swagger.io

# Docs page with /docs suffix
bytekit --swagger https://api.example.com/docs

ES: Cuando la respuesta es HTML, el CLI prueba automáticamente estas rutas comunes:

EN: When the response is HTML, the CLI automatically tries these common paths:

/openapi.json
/swagger.json
/v2/api-docs
/api-docs

ES: Internamente, el CLI delega en la función generateFromSwagger del módulo src/cli/swagger-generator.ts.

EN: Internally, the CLI delegates to the generateFromSwagger function from the src/cli/swagger-generator.ts module.

interface SwaggerOptions {
  url: string | URL;   // Swagger/OpenAPI spec URL
  output?: string;     // Default: 'src/types/api-docs.ts'
}

ES: Paso a paso de lo que sucede cuando ejecutas bytekit --swagger:

EN: Step-by-step breakdown of what happens when you run bytekit --swagger:

1. Hace fetch() a la URL proporcionada
   Performs fetch() to the provided URL

2. Inspecciona el Content-Type de la respuesta
   Inspects the response Content-Type

3. Si es HTML (Swagger UI) → intenta descubrir el spec JSON
   If HTML (Swagger UI) → tries to auto-discover the spec JSON
   Prueba: /openapi.json, /swagger.json, /v2/api-docs, /api-docs
   Tries: /openapi.json, /swagger.json, /v2/api-docs, /api-docs

4. Lee los schemas desde:
   Reads schemas from:
   • spec.components.schemas  (OpenAPI 3.x)
   • spec.definitions         (Swagger 2.x)

5. Para cada schema, genera la interfaz/tipo TypeScript
   For each schema, generates the TypeScript interface/type

6. Escribe todo en un solo archivo de salida
   Writes everything to a single output file

ES: Cada tipo del spec OpenAPI se transforma a su equivalente TypeScript. A continuación se muestra la tabla completa de transformaciones.

EN: Each OpenAPI spec type is transformed to its TypeScript equivalent. Below is the complete transformation table.

OpenAPI Schema:

{
  "Pet": {
    "type": "object",
    "required": ["id", "name"],
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" },
      "status": {
        "type": "string",
        "enum": ["available", "pending", "sold"]
      },
      "tag": { "type": "string" }
    }
  }
}

TypeScript generado / Generated TypeScript:

export interface Pet {
  id: number;
  name: string;
  status?: 'available' | 'pending' | 'sold';
  tag?: string;
}

OpenAPI Schema:

{
  "OrderStatus": {
    "type": "string",
    "enum": ["placed", "approved", "delivered"]
  }
}

TypeScript:

export type OrderStatus = 'placed' | 'approved' | 'delivered';

OpenAPI Schema:

{
  "Order": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "pet": { "$ref": "#/components/schemas/Pet" },
      "status": { "$ref": "#/components/schemas/OrderStatus" }
    }
  }
}

TypeScript:

export interface Order {
  id?: number;
  pet?: Pet;
  status?: OrderStatus;
}

OpenAPI Schema:

{
  "Response": {
    "oneOf": [
      { "$ref": "#/components/schemas/SuccessResult" },
      { "$ref": "#/components/schemas/ErrorResult" }
    ]
  }
}

TypeScript:

export type Response = (SuccessResult | ErrorResult);

OpenAPI Schema:

{
  "AdminUser": {
    "allOf": [
      { "$ref": "#/components/schemas/BaseUser" },
      {
        "type": "object",
        "properties": {
          "permissions": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    ]
  }
}

TypeScript:

export type AdminUser = (BaseUser & Record<string, any>);

OpenAPI Schema:

{
  "Metadata": {
    "type": "object",
    "additionalProperties": { "type": "string" }
  }
}

TypeScript:

export type Metadata = Record<string, string>;

OpenAPI Schema:

{
  "ExtendedUser": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" }
    },
    "additionalProperties": { "type": "string" }
  }
}

TypeScript:

export interface ExtendedUser extends Record<string, string> {
  id?: number;
  name?: string;
}

ES: Los nombres de los schemas se sanitizan eliminando todos los caracteres que no sean alfanuméricos. Esto asegura que los identificadores TypeScript generados sean válidos.

EN: Schema names are sanitized by removing all non-alphanumeric characters. This ensures the generated TypeScript identifiers are valid.

ES: También puedes usar la función directamente en código:

EN: You can also use the function directly in code:

import { generateFromSwagger } from "bytekit/cli/swagger-generator";

await generateFromSwagger({
  url: "https://petstore.swagger.io/v2/swagger.json",
  output: "src/types/petstore.ts",
});

ES: El archivo generado incluye un comentario con la fecha de generación y todas las interfaces/tipos:

EN: The generated file includes a timestamp comment and all interfaces/types:

/**
 * Auto-generated types from Swagger/OpenAPI
 * Generated at 2026-03-27T12:00:00.000Z
 */

export interface Category {
  id?: number;
  name?: string;
}

export interface Tag {
  id?: number;
  name?: string;
}

export interface Pet {
  id: number;
  name: string;
  category?: Category;
  photoUrls: string[];
  tags?: Tag[];
  status?: 'available' | 'pending' | 'sold';
}

export type OrderStatus = 'placed' | 'approved' | 'delivered';

export interface Order {
  id?: number;
  petId?: number;
  quantity?: number;
  shipDate?: string | Date;
  status?: OrderStatus;
  complete?: boolean;
}

ES: El generador soporta ambas versiones. La diferencia principal es la ubicación de los schemas:

EN: The generator supports both versions. The main difference is where schemas live:

ES: El CLI detecta automáticamente la versión y lee los schemas de la ubicación correcta.

EN: The CLI automatically detects the version and reads schemas from the correct location.

• CLI Overview — Vista general de todos los modos del CLI / Overview of all CLI modes
• CLI Type Generator — Generar tipos desde respuestas de API individuales / Generate types from individual API responses
• ApiClient — Cliente HTTP de Bytekit / Bytekit HTTP client
• SchemaAdapter — Adaptador y validación de esquemas / Schema adapter and validation