restcodegen 2.0.1
Tool for generating Python clients from OpenAPI specifications
Requires Python: <4.0,>=3.10

# RestCodeGen

[![PyPI version](https://img.shields.io/pypi/v/restcodegen.svg)](https://pypi.org/project/restcodegen)
[![Python versions](https://img.shields.io/pypi/pyversions/restcodegen.svg)](https://pypi.python.org/pypi/restcodegen)
[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/ValeriyMenshikov/restcodegen/python-test.yml?branch=main)](https://github.com/ValeriyMenshikov/restcodegen/actions/workflows/python-test.yml)
[![Coverage Status](https://coveralls.io/repos/github/ValeriyMenshikov/restcodegen/badge.svg?branch=main)](https://coveralls.io/github/ValeriyMenshikov/restcodegen?branch=main)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ValeriyMenshikov/restcodegen/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/restcodegen.svg)](https://pypistats.org/packages/restcodegen)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

<p align="center">
  <b>Generate Python clients from OpenAPI specifications with ease</b>
</p>

## 🚀 Overview

RestCodeGen is a powerful tool for automatically generating Python client libraries from OpenAPI 3 specifications. It streamlines the process of interacting with REST APIs, allowing developers and testers to quickly integrate with services that provide OpenAPI documentation.

### ✨ Key Features

- **Easy Client Generation**: Create Python clients with a single command
- **Async Support**: Generate both synchronous and asynchronous clients
- **Selective API Generation**: Choose specific API tags to include
- **Type Hints**: All generated code includes proper type annotations

## 📦 Installation

RestCodeGen requires Python 3.10 or higher. Install it using pip:

```bash
pip install restcodegen
```

Or with Poetry:

```bash
poetry add restcodegen
```

## 🔧 Usage

### Basic Command

```bash
restcodegen generate -u "http://example.com/openapi.json" -s "my-service" -a false
```

### Command Parameters

| Parameter | Short | Description | Required | Default |
|-----------|-------|-------------|----------|---------|
| `--url` | `-u` | URL of the OpenAPI specification | Yes | - |
| `--service-name` | `-s` | Name of the service | Yes | - |
| `--async-mode` | `-a` | Enable asynchronous client generation | No | `false` |
| `--api-tags` | `-t` | Comma-separated list of API tags to generate | No | All APIs |
| `--templates-dir` | `-td` | Path to directory with custom Jinja2 templates | No | Built-in templates |
| `--output-dir` | `-o` | Output directory for generated clients (root package path) | No | `./clients/http` |

### Example

### Examples

Generate a client for the Petstore API with default templates:

```bash
restcodegen generate -u "https://petstore3.swagger.io/api/v3/openapi.json" -s "petstore" -a false
```

Generate a client using custom templates:

```bash
restcodegen generate -u "https://petstore3.swagger.io/api/v3/openapi.json" -s "petstore" -a false -td ./custom_templates
```

Generate a client into a custom output directory (imports will follow this base path):

```bash
restcodegen generate -u "https://petstore3.swagger.io/api/v3/openapi.json" -s "petstore" -o framework/internal
```

### Custom Templates

You can provide your own Jinja2 templates to customize the generated code. Place your template files in a directory and specify the path using the `--templates-dir` (`-td`) option. The following template files are supported:

- `api_client.jinja2` - Main API client template
- `header.jinja2` - File header template (for license and imports)
- `apis_init.jinja2` - Data model template

To customize the output, copy the default templates from the package's `templates` directory and modify them as needed.

### Output Directory and Imports

When you specify `--output-dir` (`-o`), the generated package structure is created under that directory, for example:

```
framework/
  internal/
    petstore/
      apis/
      models/
```

All generated imports are based on the base path you provide (e.g. `framework.internal.petstore...`). If `-o` is not provided, the default base path is `clients/http`.

## 📁 Generated Structure

After successful execution, a client library will be created with the following structure:

```
└── clients                      
     └── http     
        ├── schemas               # OpenAPI 3.0.0 schemas for all generated APIs                   
        └── service_name          # Service name     
            ├── apis              # API client classes                    
            └── models            # Pydantic models   
```

## 💻 Using the Generated Client

The generated client includes built-in logging with `structlog` and supports custom HTTPX clients:

```python
from httpx import Client
from clients.http.petstore import PetApi

# Create and use the client
if __name__ == '__main__':
    # Use the httpx client or httpx.AsyncClient() for async mode
    api_client = Client(base_url="https://petstore3.swagger.io/api/v3")
    
    # Initialize the API
    pet_api = PetApi(api_client)
    
    # Make API calls
    response = pet_api.get_pet_pet_id(pet_id=1)
    print(response)
```

## 🔄 Development Workflow

1. Install development dependencies:
   ```bash
   poetry install
   ```

2. Run tests:
   ```bash
   poetry run pytest
   ```

3. Check code quality:
   ```bash
   poetry run ruff check .
   poetry run mypy .
   ```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

## 📬 Contact

For questions or feedback, please open an issue in the repository.

---

<p align="center">
  <i>RestCodeGen - Making API integration simple and efficient</i>
</p>