"""Functions for generating documentation."""
import json
import logging
from pathlib import Path
from typing import Any
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
from spoolman.api.v1.router import app as v1_app
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler()) # Print all log messages to stdout
def generate_openapi(app: FastAPI) -> dict[str, Any]:
"""Generate the OpenAPI document for a specific FastAPI app.
Args:
app (FastAPI): The FastAPI app.
Returns:
dict[str, Any]: The OpenAPI document.
"""
return get_openapi(
title=app.title,
version=app.version,
openapi_version=app.openapi_version,
description=app.description,
routes=app.routes,
contact=app.contact,
license_info=app.license_info,
servers=app.servers,
tags=app.openapi_tags,
terms_of_service=app.terms_of_service,
)
def generate_docs() -> None:
"""Generate documentation for this service in the docs/ directory."""
target_dir = Path("docs")
logger.info('Generating documentation to "%s"...', target_dir.resolve())
target_dir.mkdir(parents=True, exist_ok=True)
spec = json.dumps(generate_openapi(v1_app))
with target_dir.joinpath("index.html").open("w") as f:
f.write(
f"""
Spoolman REST API v1 - ReDoc
""",
)
logger.info("Documentation generated successfully.")