296 lines
6.9 KiB
Markdown
296 lines
6.9 KiB
Markdown
# JSON to OpenAPI Generator
|
|
|
|
|
|
|
|
|
|
|
|
A Python CLI tool that analyzes JSON data files and automatically generates valid OpenAPI 3.0 specification files. It infers data types, detects nested structures, and produces specs ready for Swagger UI, ReDoc, and code generators.
|
|
|
|
## Features
|
|
|
|
- **Automatic Type Inference**: Infers OpenAPI schema types (string, number, integer, boolean, null, array, object) from JSON data
|
|
- **Nested Object Detection**: Recursively detects nested objects and arrays to build complete schema trees
|
|
- **Format Detection**: Automatically detects date, datetime, email, URI, UUID, and byte formats
|
|
- **Batch Processing**: Process multiple JSON files in a single command with parallel processing support
|
|
- **Interactive Customization**: Interactive CLI prompts to customize endpoint names, paths, HTTP methods, and descriptions
|
|
- **OpenAPI 3.0 Output**: Generates valid OpenAPI 3.0 YAML/JSON output compatible with Swagger UI, ReDoc, and code generators
|
|
- **Validation**: Built-in validation of generated OpenAPI specs
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install json-to-openapi
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Conversion
|
|
|
|
Convert a single JSON file to OpenAPI specification:
|
|
|
|
```bash
|
|
json-to-openapi convert input.json -o output.yaml
|
|
```
|
|
|
|
### With Custom Options
|
|
|
|
```bash
|
|
json-to-openapi convert input.json \
|
|
-o output.yaml \
|
|
-t "My API" \
|
|
-v "1.0.0" \
|
|
-d "API description" \
|
|
-f yaml
|
|
```
|
|
|
|
### Interactive Mode
|
|
|
|
Interactive mode for customizing the OpenAPI specification:
|
|
|
|
```bash
|
|
json-to-openapi interactive
|
|
```
|
|
|
|
### Batch Processing
|
|
|
|
Process multiple JSON files:
|
|
|
|
```bash
|
|
json-to-openapi batch "*.json" -o ./openapi_specs/
|
|
```
|
|
|
|
Generate a combined OpenAPI spec:
|
|
|
|
```bash
|
|
json-to-openapi batch "*.json" -c -o combined.yaml
|
|
```
|
|
|
|
### Validation
|
|
|
|
Validate an existing OpenAPI specification:
|
|
|
|
```bash
|
|
json-to-openapi validate openapi.yaml
|
|
```
|
|
|
|
### Options
|
|
|
|
#### Global Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-v, --verbose` | Enable verbose output |
|
|
| `-q, --quiet` | Suppress all output except errors |
|
|
|
|
#### Convert Command
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `input_file` | Path to input JSON file |
|
|
| `-o, --output` | Output file path |
|
|
| `-f, --format` | Output format (yaml or json, default: yaml) |
|
|
| `-t, --title` | API title (default: "My API") |
|
|
| `-v, --version` | API version (default: "1.0.0") |
|
|
| `-d, --description` | API description |
|
|
|
|
#### Batch Command
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `input_pattern` | File glob pattern (e.g., "*.json" or "data/**/*.json") |
|
|
| `-o, --output-dir` | Output directory |
|
|
| `-f, --format` | Output format (yaml or json, default: yaml) |
|
|
| `-t, --title` | API title (default: "My API") |
|
|
| `-v, --version` | API version (default: "1.0.0") |
|
|
| `-c, --combined` | Generate combined OpenAPI spec |
|
|
| `-p, --parallel` | Process files in parallel |
|
|
|
|
## Examples
|
|
|
|
### Simple Object
|
|
|
|
**Input JSON:**
|
|
```json
|
|
{
|
|
"name": "John",
|
|
"age": 30,
|
|
"active": true
|
|
}
|
|
```
|
|
|
|
**Generated OpenAPI:**
|
|
```yaml
|
|
openapi: 3.0.3
|
|
info:
|
|
title: My API
|
|
version: 1.0.0
|
|
paths:
|
|
/:
|
|
get:
|
|
summary: Get My API
|
|
operationId: getMyAPI
|
|
responses:
|
|
'200':
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
age:
|
|
type: integer
|
|
active:
|
|
type: boolean
|
|
```
|
|
|
|
### Nested Structure
|
|
|
|
**Input JSON:**
|
|
```json
|
|
{
|
|
"user": {
|
|
"id": 1,
|
|
"profile": {
|
|
"name": "Alice",
|
|
"email": "alice@example.com"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The tool automatically detects nested objects and creates the appropriate schema with properties.
|
|
|
|
### Array with Objects
|
|
|
|
**Input JSON:**
|
|
```json
|
|
{
|
|
"users": [
|
|
{"id": 1, "name": "Alice"},
|
|
{"id": 2, "name": "Bob"}
|
|
]
|
|
}
|
|
```
|
|
|
|
The tool merges array object properties and generates comprehensive array item schemas.
|
|
|
|
## API Reference
|
|
|
|
### Python API
|
|
|
|
```python
|
|
from json_to_openapi.schema_generator import OpenAPIGenerator, EndpointInfo
|
|
|
|
# Create generator
|
|
generator = OpenAPIGenerator(title="My API", version="1.0.0")
|
|
|
|
# Generate spec from JSON data
|
|
data = {"name": "Test", "value": 42}
|
|
spec = generator.generate(data)
|
|
|
|
# Generate spec with custom endpoint
|
|
endpoint = EndpointInfo(
|
|
path="/items",
|
|
method="get",
|
|
summary="Get Items",
|
|
description="Retrieve all items",
|
|
tags=["items"]
|
|
)
|
|
spec = generator.generate(data, endpoint=endpoint)
|
|
|
|
# Save to file
|
|
generator.save_spec(spec, "output.yaml", format="yaml")
|
|
```
|
|
|
|
### Type Inference
|
|
|
|
The analyzer automatically detects:
|
|
|
|
- **Basic Types**: string, number, integer, boolean, null
|
|
- **String Formats**: date, date-time, email, uri, uuid, byte
|
|
- **Complex Types**: objects with properties, arrays with items
|
|
- **Required Fields**: All object properties are marked as required
|
|
- **Integer Formats**: int32 for standard integers, int64 for large integers
|
|
- **Number Formats**: double for floating-point numbers
|
|
|
|
### Error Handling
|
|
|
|
The tool handles common errors gracefully:
|
|
|
|
- **Invalid JSON**: Provides helpful error messages with line numbers
|
|
- **Empty JSON**: Validates input has valid structure
|
|
- **Invalid Output Path**: Checks path permissions and parent directory existence
|
|
- **Batch Processing**: Continues processing remaining files and reports summary at end
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
```
|
|
|
|
### Test Coverage
|
|
|
|
```bash
|
|
pytest tests/ --cov=json_to_openapi --cov-report=html
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
ruff check .
|
|
mypy .
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
json-to-openapi/
|
|
├── json_to_openapi/
|
|
│ ├── __init__.py # Package initialization
|
|
│ ├── analyzer.py # JSON type inference and analysis
|
|
│ ├── cli.py # CLI interface
|
|
│ └── schema_generator.py # OpenAPI schema generation
|
|
├── tests/
|
|
│ ├── __init__.py
|
|
│ ├── conftest.py # Pytest fixtures
|
|
│ ├── test_analyzer.py # Type inference tests
|
|
│ ├── test_schema_generator.py # Schema generation tests
|
|
│ ├── test_cli.py # CLI tests
|
|
│ └── test_integration.py # Integration tests
|
|
├── examples/
|
|
│ ├── users.json # Example user data
|
|
│ └── products.json # Example product data
|
|
├── .python-version
|
|
├── requirements.txt
|
|
├── setup.py
|
|
├── setup.cfg
|
|
├── pyproject.toml
|
|
└── README.md
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|