CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-connexion

OpenAPI/Swagger spec-first web framework for Python with automatic request validation and response serialization

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli.mddocs/

CLI Tools

Command-line interface for running development servers and managing Connexion applications. The CLI provides a convenient way to quickly start API servers directly from OpenAPI specifications.

Capabilities

Main Command

Entry point for the Connexion command-line interface.

from connexion.cli import main, create_app

def main(argv: list = None) -> None:
    """
    Main CLI entry point.
    
    Parameters:
    - argv: Command line arguments (defaults to sys.argv[1:])
    """

Run Command

Primary command for running OpenAPI specifications as web servers.

connexion run <spec_file> [base_module_path] [options]

Command Arguments

# Positional Arguments
spec_file: str          # Path to OpenAPI specification file or URL
base_module_path: str   # Root directory of handler code (optional)

# Server Options
--port, -p: int         # Port to listen on (default: 5000)
--host, -H: str         # Host interface to bind on (default: 127.0.0.1)
--app-framework, -f: str # App framework: 'async' or 'flask' (default: async)

# Development Options
--stub: bool            # Return 501 for unimplemented endpoints
--mock: str             # Return example data: 'all' or 'notimplemented'
--verbose, -v: int      # Verbosity level (0-2, use multiple -v for more verbose)

# Swagger UI Options
--swagger-ui-path: str         # URL path for API console (default: /ui)
--swagger-ui-template-dir: str # Path to custom UI template directory

# API Options
--base-path: str           # Override basePath from spec
--auth-all-paths: bool     # Enable auth for paths not in spec
--validate-responses: bool # Enable response validation
--strict-validation: bool  # Enable strict request validation

# General Options
--version: bool            # Show version information
--help: bool              # Show help message

Application Factory

Function for creating Connexion applications from CLI arguments.

def create_app(args: argparse.Namespace = None) -> AbstractApp:
    """
    Create Connexion application from CLI arguments.
    
    Parameters:
    - args: Parsed command line arguments
    
    Returns:
    AbstractApp: Configured Connexion application
    """

Available App Frameworks

AVAILABLE_APPS = {
    'async': 'connexion.apps.asynchronous.AsyncApp',  # Default
    'flask': 'connexion.apps.flask.FlaskApp'
}

Usage Examples

Basic Usage

# Run OpenAPI spec with AsyncApp (default)
connexion run openapi.yaml

# Run with Flask framework
connexion run openapi.yaml --app-framework flask

# Run on custom host and port
connexion run openapi.yaml --host 0.0.0.0 --port 8080

Development Features

# Enable stub responses for unimplemented endpoints
connexion run openapi.yaml --stub

# Mock all endpoints with example data
connexion run openapi.yaml --mock all

# Mock only unimplemented endpoints
connexion run openapi.yaml --mock notimplemented

# Enable verbose logging
connexion run openapi.yaml -v      # INFO level
connexion run openapi.yaml -vv     # DEBUG level

Swagger UI Configuration

# Custom Swagger UI path
connexion run openapi.yaml --swagger-ui-path /docs

# Custom Swagger UI template directory
connexion run openapi.yaml --swagger-ui-template-dir ./custom-ui

# Disable Swagger UI by setting empty path
connexion run openapi.yaml --swagger-ui-path ""

Validation Options

# Enable strict request validation
connexion run openapi.yaml --strict-validation

# Enable response validation
connexion run openapi.yaml --validate-responses

# Enable all validation options
connexion run openapi.yaml --strict-validation --validate-responses

Remote Specifications

# Run from remote OpenAPI specification
connexion run https://api.example.com/openapi.yaml

# Run from GitHub raw file
connexion run https://raw.githubusercontent.com/user/repo/main/openapi.yaml

Module Path Configuration

# Specify handler module path
connexion run api/openapi.yaml api/handlers

# OpenAPI spec in different directory
connexion run specs/api.yaml src/

# Current directory as module path
connexion run openapi.yaml .

Advanced Configuration

# Override base path from specification
connexion run openapi.yaml --base-path /v2

# Enable authentication for all paths
connexion run openapi.yaml --auth-all-paths

# Combination of development options
connexion run openapi.yaml \
  --mock notimplemented \
  --strict-validation \
  --validate-responses \
  --verbose \
  --swagger-ui-path /api-docs

Production-like Setup

# Production-ready configuration
connexion run openapi.yaml \
  --host 0.0.0.0 \
  --port 8000 \
  --app-framework async \
  --strict-validation \
  --validate-responses \
  --auth-all-paths

Mock Development Server

# Complete mock server for API development
connexion run openapi.yaml \
  --mock all \
  --swagger-ui-path /docs \
  --verbose

Using with Docker

# Dockerfile example
FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["connexion", "run", "openapi.yaml", "--host", "0.0.0.0", "--port", "8080"]

Environment Integration

#!/bin/bash
# Development script
export CONNEXION_HOST=${HOST:-127.0.0.1}
export CONNEXION_PORT=${PORT:-5000}
export CONNEXION_VERBOSE=${VERBOSE:-1}

connexion run openapi.yaml \
  --host $CONNEXION_HOST \
  --port $CONNEXION_PORT \
  --verbose $CONNEXION_VERBOSE \
  --mock notimplemented \
  --swagger-ui-path /ui

Custom Factory Usage

# custom_server.py
from connexion.cli import create_app
import argparse

# Create custom args
args = argparse.Namespace(
    spec_file='api.yaml',
    base_module_path=None,
    port=8000,
    host='0.0.0.0',
    app_framework='async',
    stub=False,
    mock=None,
    swagger_ui_path='/docs',
    swagger_ui_template_dir=None,
    auth_all_paths=True,
    validate_responses=True,
    strict_validation=True,
    verbose=1,
    base_path=None
)

# Create and configure app
app = create_app(args)

# Add custom configuration
if hasattr(app, 'app'):  # Flask app
    app.app.config['CUSTOM_SETTING'] = 'value'

# Run with custom logic
if __name__ == '__main__':
    app.run(host=args.host, port=args.port)

Version Information

# Show Connexion version
connexion --version

# Example output:
# Connexion 3.2.0

Help and Documentation

# Show general help
connexion --help

# Show run command help
connexion run --help

Integration Examples

CI/CD Pipeline

# .github/workflows/api-test.yml
name: API Testing
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install connexion[swagger-ui]
          
      - name: Start API server
        run: |
          connexion run openapi.yaml --mock all --port 8080 &
          sleep 5
          
      - name: Test API endpoints
        run: |
          curl -f http://localhost:8080/health
          curl -f http://localhost:8080/ui/

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "8080:8080"
    command: >
      connexion run openapi.yaml
      --host 0.0.0.0
      --port 8080
      --validate-responses
      --strict-validation
    environment:
      - CONNEXION_VERBOSE=1
    volumes:
      - ./api:/app/api
      - ./openapi.yaml:/app/openapi.yaml

Install with Tessl CLI

npx tessl i tessl/pypi-connexion

docs

applications.md

cli.md

exceptions.md

index.md

operation-resolution.md

request-response.md

security.md

validation.md

tile.json