A developer-friendly tool designed to keep your API up-to-date by leveraging OpenAPI schemas. It automates the generation of endpoint URIs and type definitions, including shared types, directly from your OpenAPI specification.
npm install openapiv3-sync

Openapi-sync is a powerful developer tool that automates the synchronization of your API documentation with your codebase using OpenAPI (formerly Swagger) specifications. It generates TypeScript types and endpoint definitions from your OpenAPI schema, ensuring your API documentation stays up-to-date with your code.
- 🔄 Real-time API Synchronization
- 📝 Automatic Type Generation
- 🔄 Periodic API Refetching
- 📁 Configurable Output Directory
- 🔄 Customizable Naming Conventions
- 🔄 Endpoint URL Transformation
- 🔄 Schema Validation
- 🔄 CLI Integration
- 🔄 TypeScript Support
- 🔄 YAML and JSON Support
Install the package using npm:
``bash`
npm install openapi-sync
Or use it directly via npx:
`bash`
npx openapi-sync
Create a openapi.sync.json file in your project root with the following structure:
`json`
{
"refetchInterval": 5000, // milliseconds between API refetches
"folder": "/path/to/output", // output directory for generated files
"api": {
"example1": "https://api.example.com/openapi.json",
"example2": "https://api.example.com/openapi.yaml"
},
"naming": {
"replaceWords": [
{
"replace": "Api",
"with": "",
"type": "endpoint"
}
]
},
"endpoints": {
"value": {
"replaceWords": [
{
"replace": "/api/v\\d/",
"with": ""
}
]
}
}
}
`bashBasic usage
npx openapi-sync
$3
`typescript
import { Init } from "openapi-sync";// Initialize with custom options
await Init({
refetchInterval: 30000, // optional, defaults to config value
});
``The tool generates:
1. TypeScript interfaces for API endpoints
2. Type definitions for request/response bodies
3. Shared component types
4. Endpoint URL constants
The tool supports:
- Primitive types (string, number, boolean, etc.)
- Complex types (objects, arrays)
- Enums
- Nullable types
- Any types
- Shared components
- Request/response bodies
The tool includes:
- Network error retries
- Schema validation
- Type generation error handling
- State persistence
For detailed API documentation, please refer to the OpenAPI specification.
This project is licensed under the ISC License - see the LICENSE file for details.
For support, please open an issue in the GitHub repository.
- Thanks to the OpenAPI Initiative for the OpenAPI specification
- Thanks to all contributors and users of this package
- Flexible CLI Commands: Sync your API at any point in the development process on app start, pre-commit, or via manual triggers.