Api Utils

docforge.cli.api_utils

Utilities for building API documentation from an OpenAPI specification.

OpenAPIMetadata(
    site_name: str,
    site_description: str | None,
    site_author: str | None,
)

Metadata derived from the info block of an OpenAPI specification.

Attributes:

Name	Type	Description
`site_name`	`str`	Spec title, used as the MkDocs site name.
`site_description`	`str \| None`	Spec description, used as the site description.
`site_author`	`str \| None`	Contact name (fallback: contact email), used as the site author.

derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata

Derive MkDocs site metadata from an OpenAPI spec info block.

Parameters:

Name	Type	Description	Default
`spec`	`dict`	Parsed OpenAPI specification.	required

Returns:

Name	Type	Description
`OpenAPIMetadata`	`OpenAPIMetadata`	Site name, description, and author derived from the spec.

generate_api_sources(
    spec: dict[Any, Any], docs_dir: Path
) -> None

Generate swagger-enabled Markdown sources and the spec copy.

The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

Parameters:

Name	Type	Description	Default
`spec`	`dict`	Parsed OpenAPI specification.	required
`docs_dir`	`Path`	Directory (for example `docs/api`) where the swagger sources are written.	required

load_openapi_spec(spec_path: Path) -> dict[Any, Any]

Load and validate an OpenAPI specification from a JSON file.

Parameters:

Name	Type	Description	Default
`spec_path`	`Path`	Path to the OpenAPI JSON specification file.	required

Returns:

Name	Type	Description
`dict`	`dict[Any, Any]`	The parsed OpenAPI specification.

Raises:

Type	Description
`ClickException`	If the file cannot be read or the `info` block is invalid.