The --swagger flag allows you to generate comprehensive TypeScript type definitions from OpenAPI/Swagger specifications. This is ideal for working with well-documented APIs.
Basic Usage
bytekit --swagger https://api.example.com/swagger.json
- Fetches the Swagger/OpenAPI specification
- Extracts all schema definitions
- Generates TypeScript interfaces
- Saves to
src/types/api-docs.ts
ByteKit supports multiple OpenAPI/Swagger formats:
- OpenAPI 3.0+ with
components.schemas
- Swagger 2.0 with
definitions
- JSON and YAML formats
Automatic Spec Discovery
If you provide a Swagger UI URL (HTML page), ByteKit automatically tries to find the JSON specification:
bytekit --swagger https://api.example.com/docs
📖 Attempting to resolve Swagger/OpenAPI spec from https://api.example.com/docs...
🔍 URL looks like a documentation page, trying to find spec JSON...
✨ Found spec at: https://api.example.com/openapi.json
/openapi.json/swagger.json/v2/api-docs/api-docs
Example with Public APIs
Petstore API
Generate types from the classic Swagger Petstore:
bytekit --swagger https://petstore.swagger.io/v2/swagger.json
📖 Attempting to resolve Swagger/OpenAPI spec from https://petstore.swagger.io/v2/swagger.json...
✅ Successfully generated 6 types!
📝 Output: /home/user/project/src/types/api-docs.ts
JSONPlaceholder OpenAPI
Generate types from a RESTful API spec:
bytekit --swagger https://jsonplaceholder.typicode.com/openapi.json
Generated Output
ByteKit generates clean, well-formatted TypeScript interfaces:
/**
* Auto-generated types from Swagger/OpenAPI
* Generated at 2026-03-04T10:30:00.000Z
*/
export interface User {
id: number;
username: string;
email: string;
firstName?: string;
lastName?: string;
phone?: string;
}
export interface Pet {
id: number;
name: string;
category?: Category;
photoUrls: string[];
tags?: Tag[];
status: 'available' | 'pending' | 'sold';
}
export interface Category {
id: number;
name: string;
}
export interface Tag {
id: number;
name: string;
}
export interface ApiResponse {
code: number;
type: string;
message: string;
}
export interface Order {
id: number;
petId: number;
quantity: number;
shipDate?: string | Date;
status: 'placed' | 'approved' | 'delivered';
complete?: boolean;
}
Type Mapping
ByteKit maps OpenAPI types to TypeScript types:
| OpenAPI Type | TypeScript Type |
|---|
string | string |
integer | number |
number | number |
boolean | boolean |
array | T[] |
object | Record<string, any> |
string (format: date) | string | Date |
string (format: date-time) | string | Date |
Schema Features
Required vs Optional Properties
ByteKit respects the required field in schemas:
User:
type: object
required:
- id
- username
properties:
id:
type: integer
username:
type: string
email:
type: string
export interface User {
id: number; // required
username: string; // required
email?: string; // optional
}
Enum Types
Enums are converted to TypeScript union types:
Pet:
properties:
status:
type: string
enum: [available, pending, sold]
export interface Pet {
status: 'available' | 'pending' | 'sold';
}
Nested Objects
Complex nested structures are preserved:
User:
properties:
address:
type: object
properties:
street:
type: string
city:
type: string
export interface User {
address?: {
street?: string;
city?: string;
};
}
Schema References
ByteKit resolves $ref references:
Pet:
properties:
category:
$ref: '#/components/schemas/Category'
export interface Pet {
category?: Category;
}
export interface Category {
id: number;
name: string;
}
Arrays
Array items are typed correctly:
User:
properties:
roles:
type: array
items:
type: string
export interface User {
roles?: string[];
}
Additional Properties
Dynamic object properties are handled:
Config:
type: object
additionalProperties:
type: string
export type Config = Record<string, string>;
OneOf / AnyOf / AllOf
ByteKit supports schema composition:
OneOf (union):
export type Pet = (Cat | Dog);
export type Response = (SuccessResponse | ErrorResponse);
export type Employee = (Person & Worker);
Output File
All generated types are saved to a single file:
The file includes:
- Auto-generation header
- Timestamp
- All exported interfaces and types
/**
* Auto-generated types from Swagger/OpenAPI
* Generated at 2026-03-04T10:30:00.000Z
*/
export interface User { /* ... */ }
export interface Pet { /* ... */ }
export interface Order { /* ... */ }
// ... all other schemas
Real-World Examples
Stripe API
bytekit --swagger https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
GitHub API
bytekit --swagger https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
Custom API
bytekit --swagger https://your-api.com/v1/swagger.json
Error Handling
ByteKit provides helpful error messages:
HTTP Error:
bytekit --swagger https://api.example.com/swagger.json
# ❌ Swagger Error: HTTP 404: Not Found
bytekit --swagger https://api.example.com/empty-spec.json
# ⚠️ No schemas or definitions found in the specification.
bytekit --swagger https://api.example.com/docs
# ❌ Swagger Error: Could not automatically find the OpenAPI/Swagger JSON
# from the documentation page. Please provide the direct JSON URL.
Tips and Best Practices
Direct JSON URLs work best: If possible, provide the direct URL to the swagger.json or openapi.json file rather than the HTML documentation page.
ByteKit sanitizes schema names by removing invalid characters, ensuring valid TypeScript identifiers.
If the spec contains no schemas or definitions, no types will be generated. Ensure your OpenAPI spec includes schema definitions.
Comparison: Type Generation vs Swagger
| Feature | --type | --swagger |
|---|
| Source | Live API response | OpenAPI/Swagger spec |
| Coverage | Single endpoint | All defined schemas |
| Output | src/types/{endpoint}.ts | src/types/api-docs.ts |
| Best for | Quick prototyping | Complete API integration |
| Documentation | Inferred from data | From spec definitions |
| Enum support | No | Yes |
| Required fields | Inferred from null | Explicit in spec |
Next Steps