Generate TypeScript interfaces and types from your service definitions for type-safe API client development.
Usage
apicentric simulator generate-types --file <INPUT> --output <OUTPUT>
Arguments
Path to the Apicentric service definition YAML file to generate types from.
Path where the generated TypeScript file will be written. Should have a .ts or .d.ts extension.
Options
--config
string
default:"apicentric.json"
Path to the configuration file (global option).
Execution mode override: ci, development, or debug (global option).
Show what would be generated without actually creating the output file (global option).
Enable verbose output for detailed logging (global option).
--db-path
string
default:"apicentric.db"
Path to the SQLite database for simulator storage (global option).
Examples
Generate TypeScript types
apicentric simulator generate-types --file services/users.yaml --output types/users.ts
✅ Exported TypeScript types to types/users.ts
Generate type definitions
apicentric simulator generate-types --file services/api.yaml --output src/@types/api.d.ts
Dry run mode
apicentric simulator generate-types --file services/users.yaml --output types.ts --dry-run
🏃 Dry run: Would export TypeScript types from 'services/users.yaml' to 'types.ts'
Generated output
The command generates TypeScript interfaces for:
- Request types - Parameters, query strings, request bodies
- Response types - Response bodies for each endpoint
- Data models - Schema definitions from your service
- Enums - Enumerated values from schema constraints
- Utility types - Helper types for API interactions
Example service definition
name: users
server:
port: 8001
types:
User:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
role:
type: string
enum: [admin, user, guest]
endpoints:
- path: /users
method: GET
response:
status: 200
body:
type: array
items:
$ref: "#/types/User"
- path: /users/:id
method: GET
response:
status: 200
body:
$ref: "#/types/User"
Generated TypeScript output
// Generated by Apicentric
// Do not edit manually
export type UserRole = 'admin' | 'user' | 'guest';
export interface User {
id: string;
name: string;
email: string;
role: UserRole;
}
export interface GetUsersResponse {
data: User[];
status: 200;
}
export interface GetUserByIdResponse {
data: User;
status: 200;
}
export interface GetUserByIdParams {
id: string;
}
// API client types
export interface UsersAPI {
getUsers(): Promise<GetUsersResponse>;
getUserById(params: GetUserByIdParams): Promise<GetUserByIdResponse>;
}
Use cases
Type-safe API client
# Generate types from service definition
apicentric simulator generate-types --file services/api.yaml --output src/types/api.ts
// Use in your application
import { User, GetUsersResponse } from './types/api';
async function fetchUsers(): Promise<User[]> {
const response = await fetch('http://localhost:8001/api/users');
const data: GetUsersResponse = await response.json();
return data.data;
}
Frontend development
# Generate types for React app
apicentric simulator generate-types --file services/api.yaml --output src/@types/api.d.ts
// components/UserList.tsx
import { User } from '@types/api';
interface UserListProps {
users: User[];
}
export const UserList: React.FC<UserListProps> = ({ users }) => {
return (
<ul>
{users.map(user => (
<li key={user.id}>{user.name} - {user.role}</li>
))}
</ul>
);
};
Contract-first development
# Generate types during development
npm run generate-types
# package.json
{
"scripts": {
"generate-types": "apicentric simulator generate-types --file services/*.yaml --output src/types/"
}
}
CI/CD type checking
# .github/workflows/typecheck.yml
name: Type Check
on: [push, pull_request]
jobs:
typecheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Generate types
run: |
apicentric simulator generate-types \
--file services/api.yaml \
--output src/types/api.ts
- name: TypeScript check
run: npm run typecheck
Batch generation for monorepos
#!/bin/bash
# generate-all-types.sh
for service in services/*.yaml; do
name=$(basename "$service" .yaml)
apicentric simulator generate-types \
--file "$service" \
--output "packages/${name}/src/types.ts"
echo "Generated types for ${name}"
done
Integration with development workflow
Watch mode with nodemon
// nodemon.json
{
"watch": ["services/**/*.yaml"],
"exec": "apicentric simulator generate-types --file services/api.yaml --output src/types/api.ts"
}
Pre-commit hook
#!/bin/bash
# .git/hooks/pre-commit
apicentric simulator generate-types \
--file services/api.yaml \
--output src/types/api.ts
git add src/types/api.ts
Build step
// package.json
{
"scripts": {
"prebuild": "apicentric simulator generate-types --file services/api.yaml --output src/types/api.ts",
"build": "tsc"
}
}
Generated types are based on your service definition schemas. Keep your service definitions up-to-date to maintain type accuracy across your application.
Best practices
- Add to .gitignore - Consider ignoring generated files and regenerating in CI
- Version control - Or commit generated types to track API changes
- Automate generation - Add to build scripts to ensure types stay in sync
- Validate first - Run
simulator validate before generating types
- Use type declarations - Generate
.d.ts files for library distribution
Troubleshooting
Failed to read service
❌ Failed to read service: No such file or directory
ls -l services/users.yaml
Invalid service YAML
❌ Invalid service YAML: missing field 'types'
types:
User:
type: object
properties:
# ...
Failed to generate types
❌ Failed to generate types: unsupported type 'unknown'
string, number, boolean, object, array.
TypeScript compilation errors
If the generated types don’t compile:
- Ensure TypeScript is configured correctly
- Check for naming conflicts with existing types
- Verify the generated output manually
- Report issues with the service definition structure