apifrom.docs.openapi

OpenAPI documentation generator for APIFromAnything.

This module provides functionality to generate OpenAPI/Swagger documentation for APIs created with the APIFromAnything library. It supports comprehensive customization options and follows the OpenAPI 3.0 specification.

Overview

Classes

• OpenAPIConfig

• OpenAPIGenerator

• Router

Functions

• extract_optional_type()

• get_args()

• get_origin()

• get_union_types()

• is_dict_type()

• is_list_type()

• is_optional_type()

• is_union_type()

• openapi_metadata()

Classes

class apifrom.docs.openapi.OpenAPIConfig(title, description, version, terms_of_service=None, contact=None, license_info=None, servers=None, external_docs=None, tags=None, security=None, components=None)

Parameters:

• title (str)

• description (str)

• version (str)

• terms_of_service (Optional[str])

• contact (Optional[Dict[str, str]])

• license_info (Optional[Dict[str, str]])

• servers (Optional[List[Dict[str, str]]])

• external_docs (Optional[Dict[str, str]])

• tags (Optional[List[Dict[str, Any]]])

• security (Optional[List[Dict[str, List[str]]]])

• components (Optional[Dict[str, Any]])

Configuration for OpenAPI documentation generation.

This class provides configuration options for customizing the OpenAPI documentation generation process.

Initialize the OpenAPI configuration.

param title:

The title of the API

param description:

The description of the API

param version:

The version of the API

param terms_of_service:

URL to the terms of service

param contact:

Contact information (name, url, email)

param license_info:

License information (name, url)

param servers:

Server information (url, description, variables)

param external_docs:

External documentation (description, url)

param tags:

API tags with descriptions

param security:

Global security requirements

param components:

Pre-defined components (schemas, responses, parameters, etc.)

class apifrom.docs.openapi.OpenAPIGenerator(title, description, version, router, config=None)

Parameters:

• title (str)

• description (str)

• version (str)

• router (apifrom.core.router.Router)

• config (Optional[OpenAPIConfig])

Generator for OpenAPI documentation.

This class generates OpenAPI/Swagger documentation for APIs created with the APIFromAnything library, with extensive customization options.

Initialize the OpenAPI generator.

param title:

The title of the API

param description:

The description of the API

param version:

The version of the API

param router:

The router instance containing the API routes

param config:

Additional configuration options

apifrom.docs.openapi._generate_components()

Generate the components section of the OpenAPI documentation.

returns:

The components section as a dictionary

apifrom.docs.openapi._generate_info()

Generate the info section of the OpenAPI documentation.

returns:

The info section as a dictionary

apifrom.docs.openapi._generate_operation(handler, method, path)

Generate an operation object for the OpenAPI documentation.

param handler:

The handler function

param method:

The HTTP method

param path:

The route path

returns:

The operation object as a dictionary

apifrom.docs.openapi._generate_paths()

Generate the paths section of the OpenAPI documentation.

returns:

The paths section as a dictionary

apifrom.docs.openapi._generate_security_schemes()

Generate the security schemes section of the OpenAPI documentation.

returns:

The security schemes section as a dictionary

apifrom.docs.openapi._get_schema_for_type(type_hint)

Generate a JSON Schema for a Python type.

param type_hint:

The Python type

returns:

A JSON Schema as a dictionary

apifrom.docs.openapi._get_security_requirements(handler)

Get security requirements for a handler.

param handler:

The handler function

returns:

A list of security requirement objects

apifrom.docs.openapi._get_summary(function_name, description)

Generate a summary for an operation.

param function_name:

The name of the function

param description:

The description from the docstring

returns:

A summary string

apifrom.docs.openapi._parse_docstring(docstring)

Parse a docstring to extract description and parameter/return descriptions.

param docstring:

The docstring to parse

returns:

A tuple containing (description, parameter_docs, return_doc, metadata)

apifrom.docs.openapi.generate()

Generate the OpenAPI documentation.

returns:

The OpenAPI documentation as a dictionary

apifrom.docs.openapi.register_callback(name, callback)

Register a custom callback.

param name:

The name of the callback

param callback:

The callback definition

apifrom.docs.openapi.register_example(name, example)

Register a custom example.

param name:

The name of the example

param example:

The example definition

apifrom.docs.openapi.register_header(name, header)

Register a custom header.

param name:

The name of the header

param header:

The header definition

apifrom.docs.openapi.register_link(name, link)

Register a custom link.

param name:

The name of the link

param link:

The link definition

apifrom.docs.openapi.register_parameter(name, parameter)

Register a custom parameter.

param name:

The name of the parameter

param parameter:

The parameter definition

apifrom.docs.openapi.register_request_body(name, request_body)

Register a custom request body.

param name:

The name of the request body

param request_body:

The request body definition

apifrom.docs.openapi.register_response(name, response)

Register a custom response.

param name:

The name of the response

param response:

The response definition

apifrom.docs.openapi.register_schema(name, schema)

Register a custom schema.

param name:

The name of the schema

param schema:

The schema definition

apifrom.docs.openapi.register_security_scheme(name, security_scheme)

Register a custom security scheme.

param name:

The name of the security scheme

param security_scheme:

The security scheme definition

apifrom.docs.openapi.to_json(indent=2)

Convert the OpenAPI documentation to JSON.

param indent:

The indentation level for the JSON output

returns:

The OpenAPI documentation as a JSON string

apifrom.docs.openapi.to_yaml()

Convert the OpenAPI documentation to YAML.

returns:

The OpenAPI documentation as a YAML string

class apifrom.docs.openapi.Router

Router for managing API endpoints.

This class is responsible for registering and looking up API endpoints. It maintains a registry of routes and their associated handlers.

apifrom.docs.openapi.routes

List of registered routes.

Type:

list

Initialize a new Router instance.

Functions

apifrom.docs.openapi.extract_optional_type(type_hint)

Parameters:

type_hint (Type)

Return type:

Type

Extract the inner type from an Optional type hint.

For types like Optional[int], this returns int.

param type_hint:

The type hint to extract from.

returns:

The inner type.

apifrom.docs.openapi.get_args(type_hint)

Parameters:

type_hint (Type)

Return type:

Tuple[Type, Ellipsis]

Get the arguments of a type hint.

For types like List[int], this returns (int,). For types like Dict[str, int], this returns (str, int).

param type_hint:

The type hint to get the arguments for.

returns:

A tuple of type arguments.

apifrom.docs.openapi.get_origin(type_hint)

Parameters:

type_hint (Type)

Return type:

Optional[Type]

Get the origin of a type hint.

For types like List[int], this returns List. For types like Dict[str, int], this returns Dict.

param type_hint:

The type hint to get the origin for.

returns:

The origin type, or None if not a generic type.

apifrom.docs.openapi.get_union_types(type_hint)

Parameters:

type_hint (Type)

Return type:

List[Type]

Get the types in a Union type hint.

param type_hint:

The type hint to get the types from.

returns:

A list of types in the Union.

apifrom.docs.openapi.is_dict_type(type_hint)

Parameters:

type_hint (Type)

Return type:

bool

Check if a type hint is a dictionary type.

param type_hint:

The type hint to check.

returns:

True if the type hint is a dictionary type, False otherwise.

apifrom.docs.openapi.is_list_type(type_hint)

Parameters:

type_hint (Type)

Return type:

bool

Check if a type hint is a list type.

param type_hint:

The type hint to check.

returns:

True if the type hint is a list type, False otherwise.

apifrom.docs.openapi.is_optional_type(type_hint)

Parameters:

type_hint (Type)

Return type:

bool

Check if a type hint is Optional.

param type_hint:

The type hint to check.

returns:

True if the type hint is Optional, False otherwise.

apifrom.docs.openapi.is_union_type(type_hint)

Parameters:

type_hint (Type)

Return type:

bool

Check if a type hint is a Union type.

param type_hint:

The type hint to check.

returns:

True if the type hint is a Union type, False otherwise.

apifrom.docs.openapi.openapi_metadata(summary=None, description=None, operation_id=None, tags=None, deprecated=None, external_docs=None, responses=None, parameters=None, request_body=None, callbacks=None, security=None)

Parameters:

• summary (Optional[str])

• description (Optional[str])

• operation_id (Optional[str])

• tags (Optional[List[str]])

• deprecated (Optional[bool])

• external_docs (Optional[Dict[str, str]])

• responses (Optional[Dict[str, Dict[str, Any]]])

• parameters (Optional[List[Dict[str, Any]]])

• request_body (Optional[Dict[str, Any]])

• callbacks (Optional[Dict[str, Dict[str, Any]]])

• security (Optional[List[Dict[str, List[str]]]])

Return type:

Callable

Decorator to add OpenAPI metadata to a function.

param summary:

A short summary of what the operation does

param description:

A verbose explanation of the operation behavior

param operation_id:

Unique string used to identify the operation

param tags:

A list of tags for API documentation control

param deprecated:

Declares this operation to be deprecated

param external_docs:

Additional external documentation

param responses:

The responses the API will return

param parameters:

Additional parameters that are not part of the function signature

param request_body:

The request body information

param callbacks:

The callbacks that can be expected from the operation

param security:

The security requirements for the operation

returns:

The decorated function