OpenAPI Documentation Generation

Automatically generates documentation from OpenAPI specification files with support for both Markdown and MkDocs styles. This MkDocs plugin processes [OAD(...)] tags in Markdown files and replaces them with comprehensive API documentation generated from OpenAPI/Swagger specifications.

Capabilities

Plugin Configuration

Configure the OpenAPI documentation plugin in your MkDocs configuration file.

class MkDocsOpenAPIDocumentationPlugin(BasePlugin):
    """
    MkDocs plugin for generating documentation from OpenAPI specification files.
    
    Configuration:
    - use_pymdownx (bool): Whether to use PyMdown extensions for enhanced Markdown
    """
    config_scheme = (("use_pymdownx", Type(bool, default=False)),)

Markdown Processing

The plugin processes Markdown content during the build phase, replacing OpenAPI tags with generated documentation.

def on_page_markdown(self, markdown, page, *args, **kwargs):
    """
    Processes Markdown content to replace [OAD(...)] tags with OpenAPI documentation.
    
    Parameters:
    - markdown (str): The Markdown content of the page
    - page (Page): The MkDocs page object
    
    Returns:
    str: Modified Markdown with OpenAPI documentation injected
    """

Style Configuration

The plugin supports different output styles based on your MkDocs setup.

def _get_style(self) -> str:
    """
    Returns the documentation style based on configuration.
    
    Returns:
    str: "MKDOCS" if use_pymdownx is True, "MARKDOWN" otherwise
    """

Usage Examples

Basic Usage

Add the plugin to your mkdocs.yml:

plugins:
  - neoteroi.mkdocsoad

In your Markdown files, reference OpenAPI specifications:

# API Documentation

[OAD(./openapi.yaml)]

Advanced Configuration

Configure the plugin with PyMdown extensions:

plugins:
  - neoteroi.mkdocsoad:
      use_pymdownx: true

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed

Supported Source Types

The plugin supports various OpenAPI specification sources:

<!-- Local YAML file -->
[OAD(./specs/api.yaml)]

<!-- Local JSON file -->
[OAD(./specs/api.json)]

<!-- Relative path -->
[OAD(../shared/openapi.yaml)]

<!-- URL (if supported by underlying library) -->
[OAD(https://example.com/api/openapi.json)]

Multiple API Specifications

Include multiple API specifications in a single page:

# API Documentation

## User API
[OAD(./user-api.yaml)]

## Product API
[OAD(./product-api.yaml)]

## Orders API
[OAD(./orders-api.yaml)]

Integration

MkDocs Integration

The plugin integrates seamlessly with MkDocs' build process:

1. Reads OpenAPI specification files during page processing
2. Generates Markdown documentation using essentials-openapi library
3. Injects generated content into the page before final rendering
4. Supports MkDocs' file resolution and path handling

Error Handling

The plugin handles various error conditions gracefully:

• Missing OpenAPI specification files are logged as warnings
• Invalid OpenAPI specifications are reported with detailed error messages
• Malformed [OAD(...)] tags are left unchanged and logged

Performance Considerations

• OpenAPI specifications are processed once per build
• Large API specifications may increase build time
• Consider using local files rather than remote URLs for better performance