apifrom.docs

Documentation generation module for APIFromAnything.

This module provides functionality for generating documentation for APIs created with the APIFromAnything library.

Overview

Classes

Classes

class apifrom.docs.OpenAPIConfig(title, description, version, terms_of_service=None, contact=None, license_info=None, servers=None, external_docs=None, tags=None, security=None, components=None)[source]
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.OpenAPIGenerator(title, description, version, router, config=None)[source]
Parameters:

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._generate_components()

Generate the components section of the OpenAPI documentation.

returns:

The components section as a dictionary

apifrom.docs._generate_info()

Generate the info section of the OpenAPI documentation.

returns:

The info section as a dictionary

apifrom.docs._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._generate_paths()

Generate the paths section of the OpenAPI documentation.

returns:

The paths section as a dictionary

apifrom.docs._generate_security_schemes()

Generate the security schemes section of the OpenAPI documentation.

returns:

The security schemes section as a dictionary

apifrom.docs._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._get_security_requirements(handler)

Get security requirements for a handler.

param handler:

The handler function

returns:

A list of security requirement objects

apifrom.docs._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._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.generate()

Generate the OpenAPI documentation.

returns:

The OpenAPI documentation as a dictionary

apifrom.docs.register_callback(name, callback)

Register a custom callback.

param name:

The name of the callback

param callback:

The callback definition

apifrom.docs.register_example(name, example)

Register a custom example.

param name:

The name of the example

param example:

The example definition

apifrom.docs.register_header(name, header)

Register a custom header.

param name:

The name of the header

param header:

The header definition

Register a custom link.

param name:

The name of the link

param link:

The link definition

apifrom.docs.register_parameter(name, parameter)

Register a custom parameter.

param name:

The name of the parameter

param parameter:

The parameter definition

apifrom.docs.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.register_response(name, response)

Register a custom response.

param name:

The name of the response

param response:

The response definition

apifrom.docs.register_schema(name, schema)

Register a custom schema.

param name:

The name of the schema

param schema:

The schema definition

apifrom.docs.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.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.to_yaml()

Convert the OpenAPI documentation to YAML.

returns:

The OpenAPI documentation as a YAML string

class apifrom.docs.SwaggerUI(openapi_generator, url_prefix='/docs', config=None, assets_dir=None, static_files_route='/static')[source]
Parameters:

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

apifrom.docs._create_default_templates()

Create default templates if they don’t exist.

apifrom.docs._create_theme_files()

Create CSS files for the different themes.

apifrom.docs._get_default_css()

Get the default custom CSS.

returns:

The default custom CSS for Swagger UI.

apifrom.docs._get_default_template()

Get the default HTML template.

returns:

The default HTML template for Swagger UI.

apifrom.docs._get_flattop_theme()

Get the Flattop theme CSS.

apifrom.docs._get_material_theme()

Get the Material theme CSS.

apifrom.docs._get_muted_theme()

Get the Muted theme CSS.

apifrom.docs._get_outline_theme()

Get the Outline theme CSS.

apifrom.docs._setup_static_files()

Set up static files for Swagger UI.

returns:

Static files mounted app if assets_dir is provided, None otherwise.

apifrom.docs.openapi_json(request)
:async:

Serve the OpenAPI JSON.

param request:

The request object.

returns:

JSON response with the OpenAPI specification.

apifrom.docs.setup_routes()

Set up routes for Swagger UI.

returns:

A list of routes for Swagger UI.

apifrom.docs.swagger_ui_html(request)
:async:

Serve the Swagger UI HTML page.

param request:

The request object

returns:

A response containing the Swagger UI HTML

class apifrom.docs.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)[source]
Parameters:

  • theme (str)

  • deep_linking (bool)

  • display_operation_id (bool)

  • default_models_expand_depth (int)

  • default_model_expand_depth (int)

  • default_model_rendering (str)

  • display_request_duration (bool)

  • doc_expansion (str)

  • filter (bool)

  • max_displayed_tags (Optional[int])

  • operations_sorter (Optional[str])

  • show_extensions (bool)

  • show_common_extensions (bool)

  • tag_sorter (Optional[str])

  • use_unicode_characters (bool)

  • persist_authorization (bool)

  • syntax_highlight (str)

  • oauth2_redirect_url (Optional[str])

  • custom_css (Optional[str])

  • custom_js (Optional[str])

  • custom_favicon (Optional[str])

  • custom_swagger_ui_version (str)

  • dom_id (str)

  • layout (str)

  • plugins (Optional[List[str]])

  • presets (Optional[List[str]])

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

apifrom.docs.to_dict()

Convert the configuration to a dictionary.

returns:

A dictionary with the configuration options.