# OpenAPI Specification Splitting
This document explains how to split large OpenAPI specifications into smaller, more manageable files using the redocly CLI tool.
## Overview
The DataDog API specifications are very large:
- **v1 API**: ~15,000 lines
- **v2 API**: ~70,000 lines
Splitting these specifications makes them easier to:
- Navigate and understand
- Edit and maintain
- Version control
- Generate documentation
## Available Make Targets
### Split Commands
```bash
# Split both v1 and v2 OpenAPI specifications
make split
# Split only DataDog API v1 specification
make split-v1
# Split only DataDog API v2 specification
make split-v2
```
### Clean Commands
```bash
# Clean split files only
make clean-split
# Clean everything (including split files)
make clean-all
```
### Installation
```bash
# Install redocly CLI tool
make install-redocly
# Install all development tools (includes redocly)
make install-dev-tools
```
## Split Structure
When you run the split commands, the following structure is created:
```bash
schemas/
├── v1/
│ ├── openapi.yaml # Original specification
│ └── split/ # Split files
│ ├── openapi.yaml # Main file with $ref pointers
│ ├── components/ # Reusable components
│ │ ├── schemas/ # Data models
│ │ ├── parameters/ # Parameter definitions
│ │ ├── responses/ # Response definitions
│ │ └── ...
│ └── paths/ # API endpoints
│ ├── api_v1_dashboards.yaml
│ ├── api_v1_events.yaml
│ └── ...
└── v2/
├── openapi.yaml # Original specification
└── split/ # Split files
├── openapi.yaml # Main file with $ref pointers
├── components/ # Reusable components
│ ├── schemas/ # Data models (3000+ files)
│ ├── parameters/ # Parameter definitions
│ ├── responses/ # Response definitions
│ └── ...
└── paths/ # API endpoints (300+ files)
├── api_v2_dashboards.yaml
├── api_v2_events.yaml
└── ...
```
## How It Works
The redocly CLI tool:
1. **Analyzes** the original OpenAPI specification
2. **Extracts** components (schemas, parameters, responses) into separate files
3. **Splits** paths into individual endpoint files
4. **Creates** a main `openapi.yaml` file with `$ref` pointers to the split files
5. **Preserves** all references and relationships
## Benefits
### For Development
- **Easier Navigation**: Find specific endpoints or schemas quickly
- **Better Version Control**: Smaller files with focused changes
- **Reduced Conflicts**: Multiple developers can work on different parts
- **Faster Loading**: IDEs and tools load smaller files faster
### For Documentation
- **Modular Documentation**: Generate docs for specific API sections
- **Better Organization**: Group related endpoints and schemas
- **Easier Maintenance**: Update specific parts without affecting others
### For Code Generation
- **Selective Generation**: Generate code for specific API sections
- **Faster Processing**: Smaller files process faster
- **Better Error Handling**: Easier to identify issues in specific areas
## Usage Examples
### Split All Specifications
```bash
# Split both v1 and v2 specifications
make split
```
### Work with Split Files
```bash
# View the main split file
cat schemas/v2/split/openapi.yaml
# View a specific endpoint
cat schemas/v2/split/paths/api_v2_dashboards.yaml
# View a specific schema
cat schemas/v2/split/components/schemas/Dashboard.yaml
```
### Clean Up
```bash
# Remove split files when done
make clean-split
```
## Integration with Code Generation
The split files can be used with `oapi-codegen` for more targeted code generation:
```bash
# Generate code from specific split files
oapi-codegen -generate types,client -package v2 schemas/v2/split/openapi.yaml > internal/api/v2/client.gen.go
# Generate code from specific endpoint groups
oapi-codegen -generate types,client -package dashboards schemas/v2/split/paths/api_v2_dashboards.yaml
```
## Best Practices
1. **Keep Original Files**: Always keep the original `openapi.yaml` files as the source of truth
2. **Use Split for Development**: Use split files for navigation and development
3. **Regenerate When Updated**: Re-split when the original specifications are updated
4. **Clean Regularly**: Remove split files when not needed to save space
5. **Version Control**: Consider adding `split/` directories to `.gitignore`
## Troubleshooting
### Redocly CLI Not Found
```bash
# Install redocly CLI
make install-redocly
# Or install all dev tools
make install-dev-tools
```
### Split Files Not Created
```bash
# Check if redocly is installed
which redocly
# Run with verbose output
redocly split schemas/v2/openapi.yaml --outDir schemas/v2/split/ --verbose
```
### Large File Sizes
The v2 API split creates many files (3000+ schemas, 300+ paths). This is normal and expected for such a large API specification.
## Related Documentation
- [Available Tools](tools.md) - List of implementable DataDog tools
- [Test Documentation](tests.md) - Test coverage and implementation details
- [README](../README.md) - Project overview and quick start guide