Openapi-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.

Features

• 🔄 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

Installation

Install the package using npm:

1npm install openapi-sync

Or use it directly via npx:

1npx openapi-sync

Configuration

Create a openapi.sync.json file in your project root with the following structure:

1{
2  "refetchInterval": 5000, // milliseconds between API refetches
3  "folder": "/path/to/output", // output directory for generated files
4  "api": {
5    "example1": "https://api.example.com/openapi.json",
6    "example2": "https://api.example.com/openapi.yaml"
7  },
8  "naming": {
9    "replaceWords": [
10      {
11        "replace": "Api",
12        "with": "",
13        "type": "endpoint"
14      }
15    ]
16  },
17  "endpoints": {
18    "value": {
19      "replaceWords": [
20        {
21          "replace": "/api/v\\d/",
22          "with": ""
23        }
24      ]
25    }
26  }
27}

Usage

CLI Commands

1# Basic usage
2npx openapi-sync
3
4# With custom refetch interval
5npx openapi-sync --refreshinterval 30000

Programmatic Usage

1import { Init } from "openapi-sync";
2
3// Initialize with custom options
4await Init({
5  refetchInterval: 30000, // optional, defaults to config value
6});

Output Generation

The tool generates:

1. TypeScript interfaces for API endpoints
2. Type definitions for request/response bodies
3. Shared component types
4. Endpoint URL constants

Type Generation

The tool supports:

• Primitive types (string, number, boolean, etc.)
• Complex types (objects, arrays)
• Enums
• Nullable types
• Any types
• Shared components
• Request/response bodies

Error Handling

The tool includes:

• Network error retries
• Schema validation
• Type generation error handling
• State persistence

API Documentation

For detailed API documentation, please refer to the OpenAPI specification.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Support

For support, please open an issue in the GitHub repository.

Acknowledgments

• 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.