apifrom.docs ============ Documentation generation module for APIFromAnything. This module provides functionality for generating documentation for APIs created with the APIFromAnything library. .. py:currentmodule:: apifrom.docs Overview -------- **Classes** * :py:class:`OpenAPIConfig` * :py:class:`OpenAPIGenerator` * :py:class:`SwaggerUI` * :py:class:`SwaggerUIConfig` 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:: SwaggerUI(openapi_generator, url_prefix = '/docs', config = None, assets_dir = None, static_files_route = '/static') Swagger UI for APIFromAnything. This class provides a Swagger UI integration for APIs created with the APIFromAnything library, with extensive customization options. Initialize the Swagger UI. :param openapi_generator: The OpenAPI generator instance :param url_prefix: The URL prefix for the documentation :param config: The Swagger UI configuration :param assets_dir: Directory containing custom assets (CSS, JS, images) :param static_files_route: The route for static files .. :: assets_dir .. :: config :no-index: .. :: openapi_generator .. :: static_files_route .. :: templates .. :: templates_path .. :: url_prefix .. method:: _create_default_templates() Create default templates if they don't exist. .. method:: _create_theme_files() Create CSS files for the different themes. .. method:: _get_default_css() Get the default custom CSS. :returns: The default custom CSS for Swagger UI. .. method:: _get_default_template() Get the default HTML template. :returns: The default HTML template for Swagger UI. .. method:: _get_flattop_theme() Get the Flattop theme CSS. .. method:: _get_material_theme() Get the Material theme CSS. .. method:: _get_muted_theme() Get the Muted theme CSS. .. method:: _get_outline_theme() Get the Outline theme CSS. .. method:: _setup_static_files() Set up static files for Swagger UI. :returns: Static files mounted app if assets_dir is provided, None otherwise. .. method:: openapi_json(request) :async: Serve the OpenAPI JSON. :param request: The request object. :returns: JSON response with the OpenAPI specification. .. method:: setup_routes() Set up routes for Swagger UI. :returns: A list of routes for Swagger UI. .. method:: swagger_ui_html(request) :async: Serve the Swagger UI HTML page. :param request: The request object :returns: A response containing the Swagger UI HTML .. py:class:: SwaggerUIConfig(theme = 'default', deep_linking = True, display_operation_id = False, default_models_expand_depth = 1, default_model_expand_depth = 1, default_model_rendering = 'example', display_request_duration = True, doc_expansion = 'list', filter = True, max_displayed_tags = None, operations_sorter = None, show_extensions = False, show_common_extensions = False, tag_sorter = None, use_unicode_characters = True, persist_authorization = False, syntax_highlight = 'monokai', oauth2_redirect_url = None, custom_css = None, custom_js = None, custom_favicon = None, custom_swagger_ui_version = '5.9.1', dom_id = '#swagger-ui', layout = 'StandaloneLayout', plugins = None, presets = None) Configuration for Swagger UI customization. This class provides extensive configuration options for customizing the appearance and behavior of the Swagger UI documentation. Initialize the Swagger UI configuration. :param theme: The theme to use (default, material, muted, outline, flattop) :param deep_linking: If set to true, enables deep linking for tags and operations :param display_operation_id: Controls the display of operationId in operations list :param default_models_expand_depth: The default expansion depth for models (set to -1 completely hide the models) :param default_model_expand_depth: The default expansion depth for the model on the model-example section :param default_model_rendering: Controls how the model is shown when the API is first rendered :param display_request_duration: Controls the display of the request duration (in milliseconds) for Try-It-Out requests :param doc_expansion: Controls the default expansion setting for the operations and tags :param filter: If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown :param max_displayed_tags: If set, limits the number of tagged operations displayed to at most this many :param operations_sorter: Apply a sort to the operation list of each API :param show_extensions: Controls the display of vendor extension (x-) fields and values :param show_common_extensions: Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values :param tag_sorter: Apply a sort to the tag list :param use_unicode_characters: Controls whether unicode characters are used in rendered descriptions :param persist_authorization: If set, will persist authorization data :param syntax_highlight: Syntax highlighting theme (agate, arta, monokai, nord, obsidian, etc.) :param oauth2_redirect_url: OAuth2 redirect URL :param custom_css: URL to a custom CSS file :param custom_js: URL to a custom JavaScript file :param custom_favicon: URL to a custom favicon :param custom_swagger_ui_version: The version of Swagger UI to use :param dom_id: The DOM element ID to bind to :param layout: The layout to use (BaseLayout, StandaloneLayout) :param plugins: The plugins to use :param presets: The presets to use .. :: custom_css .. :: custom_favicon .. :: custom_js .. :: custom_swagger_ui_version .. :: deep_linking .. :: default_model_expand_depth .. :: default_model_rendering .. :: default_models_expand_depth .. :: display_operation_id .. :: display_request_duration .. :: doc_expansion .. :: dom_id .. :: filter .. :: layout .. :: max_displayed_tags .. :: oauth2_redirect_url .. :: operations_sorter .. :: persist_authorization .. :: plugins .. :: presets .. :: show_common_extensions .. :: show_extensions .. :: syntax_highlight .. :: tag_sorter .. :: theme .. :: use_unicode_characters .. method:: to_dict() Convert the configuration to a dictionary. :returns: A dictionary with the configuration options.