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. .. py:currentmodule:: apifrom.docs.openapi Overview -------- **Classes** * :py:class:`OpenAPIConfig` * :py:class:`OpenAPIGenerator` * :py:class:`Router` **Functions** * :py:func:`extract_optional_type` * :py:func:`get_args` * :py:func:`get_origin` * :py:func:`get_union_types` * :py:func:`is_dict_type` * :py:func:`is_list_type` * :py:func:`is_optional_type` * :py:func:`is_union_type` * :py:func:`openapi_metadata` Classes ------- .. py:class:: OpenAPIConfig(title, description, version, terms_of_service = None, contact = None, license_info = None, servers = None, external_docs = None, tags = None, security = None, components = None) 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.) .. :: components .. :: contact .. :: description .. :: external_docs .. :: license_info .. :: security .. :: servers .. :: tags .. :: terms_of_service .. :: title .. :: version .. py:class:: OpenAPIGenerator(title, description, version, router, config = None) 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 .. :: config :no-index: .. :: custom_callbacks :annotation: Dict[str, Dict[str, Any]] .. :: custom_examples :annotation: Dict[str, Dict[str, Any]] .. :: custom_headers :annotation: Dict[str, Dict[str, Any]] .. :: custom_links :annotation: Dict[str, Dict[str, Any]] .. :: custom_parameters :annotation: Dict[str, Dict[str, Any]] .. :: custom_request_bodies :annotation: Dict[str, Dict[str, Any]] .. :: custom_responses :annotation: Dict[str, Dict[str, Any]] .. :: custom_schemas :annotation: Dict[str, Dict[str, Any]] .. :: custom_security_schemes :annotation: Dict[str, Dict[str, Any]] .. :: router .. method:: _generate_components() Generate the components section of the OpenAPI documentation. :returns: The components section as a dictionary .. method:: _generate_info() Generate the info section of the OpenAPI documentation. :returns: The info section as a dictionary .. method:: _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 .. method:: _generate_paths() Generate the paths section of the OpenAPI documentation. :returns: The paths section as a dictionary .. method:: _generate_security_schemes() Generate the security schemes section of the OpenAPI documentation. :returns: The security schemes section as a dictionary .. method:: _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 .. method:: _get_security_requirements(handler) Get security requirements for a handler. :param handler: The handler function :returns: A list of security requirement objects .. method:: _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 .. method:: _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) .. method:: generate() Generate the OpenAPI documentation. :returns: The OpenAPI documentation as a dictionary .. method:: register_callback(name, callback) Register a custom callback. :param name: The name of the callback :param callback: The callback definition .. method:: register_example(name, example) Register a custom example. :param name: The name of the example :param example: The example definition .. method:: register_header(name, header) Register a custom header. :param name: The name of the header :param header: The header definition .. method:: register_link(name, link) Register a custom link. :param name: The name of the link :param link: The link definition .. method:: register_parameter(name, parameter) Register a custom parameter. :param name: The name of the parameter :param parameter: The parameter definition .. method:: 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 .. method:: register_response(name, response) Register a custom response. :param name: The name of the response :param response: The response definition .. method:: register_schema(name, schema) Register a custom schema. :param name: The name of the schema :param schema: The schema definition .. method:: 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 .. method:: 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 .. method:: to_yaml() Convert the OpenAPI documentation to YAML. :returns: The OpenAPI documentation as a YAML string .. py:class:: 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. .. attribute:: routes List of registered routes. :type: list Initialize a new Router instance. Functions --------- .. py:function:: extract_optional_type(type_hint) 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. .. py:function:: get_args(type_hint) 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. .. py:function:: get_origin(type_hint) 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. .. py:function:: get_union_types(type_hint) 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. .. py:function:: is_dict_type(type_hint) 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. .. py:function:: is_list_type(type_hint) 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. .. py:function:: is_optional_type(type_hint) 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. .. py:function:: is_union_type(type_hint) 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. .. py:function:: 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) 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