209 lines
6.5 KiB
Python
209 lines
6.5 KiB
Python
"""
|
|
OpenAPI Schema Creator Module
|
|
|
|
This module provides functionality to create and customize OpenAPI documentation:
|
|
- Custom security schemes (Bearer Auth, API Key)
|
|
- Response schemas and examples
|
|
- Tag management and descriptions
|
|
- Error responses and validation
|
|
- Custom documentation extensions
|
|
"""
|
|
|
|
from typing import Any, Dict, List, Optional, Set
|
|
from fastapi import FastAPI, APIRouter
|
|
from fastapi.openapi.utils import get_openapi
|
|
from AllConfigs.main import MainConfig as Config
|
|
|
|
|
|
class OpenAPISchemaCreator:
|
|
"""
|
|
OpenAPI schema creator and customizer for FastAPI applications.
|
|
"""
|
|
|
|
def __init__(self, app: FastAPI):
|
|
"""
|
|
Initialize the OpenAPI schema creator.
|
|
|
|
Args:
|
|
app: FastAPI application instance
|
|
"""
|
|
self.app = app
|
|
self.protected_paths: Set[str] = set()
|
|
self.tags_metadata = self._create_tags_metadata()
|
|
|
|
@staticmethod
|
|
def _create_tags_metadata() -> List[Dict[str, str]]:
|
|
"""
|
|
Create metadata for API tags.
|
|
|
|
Returns:
|
|
List[Dict[str, str]]: List of tag metadata
|
|
"""
|
|
return [
|
|
{
|
|
"name": "Authentication",
|
|
"description": "Operations related to user authentication and authorization",
|
|
},
|
|
{
|
|
"name": "Users",
|
|
"description": "User management and profile operations",
|
|
},
|
|
# Add more tags as needed
|
|
]
|
|
|
|
def _create_security_schemes(self) -> Dict[str, Any]:
|
|
"""
|
|
Create security scheme definitions.
|
|
|
|
Returns:
|
|
Dict[str, Any]: Security scheme configurations
|
|
"""
|
|
return {
|
|
"Bearer Auth": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "evyos-session-key",
|
|
"description": "Enter: **'Bearer <JWT>'**, where JWT is the access token",
|
|
},
|
|
"API Key": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "X-API-Key",
|
|
"description": "API key for service authentication",
|
|
},
|
|
}
|
|
|
|
def _create_common_responses(self) -> Dict[str, Any]:
|
|
"""
|
|
Create common response schemas.
|
|
|
|
Returns:
|
|
Dict[str, Any]: Common response configurations
|
|
"""
|
|
return {
|
|
"401": {
|
|
"description": "Unauthorized - Authentication failed or not provided",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"detail": {"type": "string"},
|
|
"error_code": {"type": "string"},
|
|
},
|
|
},
|
|
"example": {
|
|
"detail": "Invalid authentication credentials",
|
|
"error_code": "INVALID_CREDENTIALS",
|
|
},
|
|
}
|
|
},
|
|
},
|
|
"403": {
|
|
"description": "Forbidden - Insufficient permissions",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {"$ref": "#/components/schemas/HTTPValidationError"}
|
|
}
|
|
},
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {"$ref": "#/components/schemas/HTTPValidationError"}
|
|
}
|
|
},
|
|
},
|
|
"500": {
|
|
"description": "Internal Server Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"detail": {"type": "string"},
|
|
"error_code": {"type": "string"},
|
|
},
|
|
},
|
|
"example": {
|
|
"detail": "Internal server error occurred",
|
|
"error_code": "INTERNAL_ERROR",
|
|
},
|
|
}
|
|
},
|
|
},
|
|
}
|
|
|
|
def configure_route_security(
|
|
self, path: str, method: str, schema: Dict[str, Any]
|
|
) -> None:
|
|
"""
|
|
Configure security requirements for a specific route.
|
|
|
|
Args:
|
|
path: Route path
|
|
method: HTTP method
|
|
schema: OpenAPI schema to modify
|
|
"""
|
|
if path not in Config.INSECURE_PATHS:
|
|
schema["paths"][path][method]["security"] = [
|
|
{"Bearer Auth": []},
|
|
{"API Key": []},
|
|
]
|
|
schema["paths"][path][method]["responses"].update(
|
|
self._create_common_responses()
|
|
)
|
|
|
|
def create_schema(self) -> Dict[str, Any]:
|
|
"""
|
|
Create the complete OpenAPI schema.
|
|
|
|
Returns:
|
|
Dict[str, Any]: Complete OpenAPI schema
|
|
"""
|
|
openapi_schema = get_openapi(
|
|
title=Config.TITLE,
|
|
description=Config.DESCRIPTION,
|
|
version="1.0.0",
|
|
routes=self.app.routes,
|
|
tags=self.tags_metadata,
|
|
)
|
|
|
|
# Add security schemes
|
|
if "components" not in openapi_schema:
|
|
openapi_schema["components"] = {}
|
|
|
|
openapi_schema["components"]["securitySchemes"] = self._create_security_schemes()
|
|
|
|
# Configure route security and responses
|
|
for route in self.app.routes:
|
|
if isinstance(route, APIRoute) and route.include_in_schema:
|
|
path = str(route.path)
|
|
methods = [method.lower() for method in route.methods]
|
|
|
|
for method in methods:
|
|
self.configure_route_security(path, method, openapi_schema)
|
|
|
|
# Add custom documentation extensions
|
|
openapi_schema["x-documentation"] = {
|
|
"postman_collection": "/docs/postman",
|
|
"swagger_ui": "/docs",
|
|
"redoc": "/redoc",
|
|
}
|
|
|
|
return openapi_schema
|
|
|
|
|
|
def create_openapi_schema(app: FastAPI) -> Dict[str, Any]:
|
|
"""
|
|
Create OpenAPI schema for a FastAPI application.
|
|
|
|
Args:
|
|
app: FastAPI application instance
|
|
|
|
Returns:
|
|
Dict[str, Any]: Complete OpenAPI schema
|
|
"""
|
|
creator = OpenAPISchemaCreator(app)
|
|
return creator.create_schema() |