fastapi-postman-exporter 0.1.1
Export FastAPI applications to Postman collections
License: MIT
Requires Python: >=3.8
Keywords: api, export, fastapi, openapi, postman

# FastAPI Postman Exporter

A Python package to export FastAPI applications to Postman collections using the OpenAPI specification.

## Features

- 🚀 Export any FastAPI app to a Postman collection
- 🔧 CLI interface for easy integration
- 📦 Simple Python API for programmatic use
- 🎯 Automatic OpenAPI spec generation
- ✅ Validation and error handling

## Prerequisites

Before using this package, you need to install the `openapi2postmanv2` CLI tool:

### Install Node.js and npm

1. Download and install Node.js from [nodejs.org](https://nodejs.org/)
2. Verify installation:
   ```bash
   node --version
   npm --version
   ```

### Install openapi2postmanv2

```bash
npm install -g openapi2postmanv2
```

Verify the installation:
```bash
openapi2postmanv2 --version
```

## Installation

### From PyPI (recommended)

```bash
pip install fastapi-postman-exporter
```

### From source

```bash
git clone https://github.com/Akshya107/fastapi-postman-exporter.git
cd fastapi-postman-exporter
pip install -e .
```

## Usage

### CLI Usage

The package provides a command-line interface for easy export:

```bash
# Basic usage
fastapi-postman-exporter export --app-path main.py --app-name app --output collection.json

# With custom app name
fastapi-postman-exporter export --app-path api/main.py --app-name api_app --output postman_collection.json

# With verbose output
fastapi-postman-exporter export --app-path main.py --app-name app --output collection.json --verbose
```

#### CLI Options

- `--app-path` / `-p`: Path to your FastAPI app file (e.g., `main.py`)
- `--app-name` / `-n`: Name of the FastAPI app object in the file (default: `app`)
- `--output` / `-o`: Path where the Postman collection JSON will be saved
- `--verbose` / `-v`: Enable verbose output

#### Check CLI Tool Installation

```bash
fastapi-postman-exporter check
```

### Python API Usage

You can also use the package programmatically:

```python
from fastapi import FastAPI
from fastapi_postman_exporter import generate_postman_from_app

# Your FastAPI app
app = FastAPI(title="My API", version="1.0.0")

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

# Export to Postman collection
generate_postman_from_app(app, "my_api_collection.json")
```

## Example FastAPI App

Here's a simple example of a FastAPI app that can be exported:

```python
# main.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="Sample API",
    description="A sample API for demonstration",
    version="1.0.0"
)

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

@app.post("/items/")
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}
```

Export this app:
```bash
fastapi-postman-exporter export --app-path main.py --app-name app --output sample_api_collection.json
```

## Project Structure

```
fastapi_postman_exporter/
├── __init__.py          # Package initialization
├── exporter.py          # Core export functionality
├── cli.py              # CLI interface
└── main.py             # CLI entry point
```

## Development

### Setup Development Environment

```bash
git clone https://github.com/Akshya107/fastapi-postman-exporter.git
cd fastapi-postman-exporter
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Code Formatting

```bash
black fastapi_postman_exporter/
isort fastapi_postman_exporter/
```

### Type Checking

```bash
mypy fastapi_postman_exporter/
```

## How It Works

1. **OpenAPI Generation**: Uses FastAPI's built-in `openapi()` method to generate the OpenAPI specification
2. **Temporary File**: Writes the OpenAPI spec to a temporary JSON file
3. **Conversion**: Uses the `openapi2postmanv2` CLI tool to convert the OpenAPI spec to a Postman collection
4. **Cleanup**: Removes the temporary file and outputs the Postman collection

## Error Handling

The package provides helpful error messages for common issues:

- **CLI tool not installed**: Clear instructions to install `openapi2postmanv2`
- **App loading errors**: Detailed error messages for file not found, invalid app name, etc.
- **Conversion errors**: Captures and displays subprocess errors from the conversion tool

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## License

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

## Support

If you encounter any issues or have questions:

1. Check the [Issues](https://github.com/Akshya107/fastapi-postman-exporter/issues) page
2. Create a new issue with detailed information about your problem
3. Include your FastAPI app code and the exact error message

## Changelog

### 0.1.0
- Initial release
- CLI interface with export and check commands
- Python API for programmatic use
- Support for dynamic FastAPI app loading
- Comprehensive error handling