edX API Doc Tools

3.0.0 verified Mon Apr 27 auth: no python

Tools for writing and generating API documentation for edX REST APIs. Current version 3.0.0 (dropped Python 3.11 support). Release cadence: irregular, with major version bumps for Python/Django support drops.

pip install edx-api-doc-tools

Common errors

error ModuleNotFoundError: No module named 'api_doc_tools' ↓

cause Incorrect import path; missing 'edx_' prefix or using hyphens.

fix

Install and import as 'edx_api_doc_tools' (underscores, no hyphens).

error AttributeError: module 'edx_api_doc_tools' has no attribute 'create_api_doc' ↓

cause Older version (<1.0?) or typo in function name.

fix

Check installed version: pip show edx-api-doc-tools. Ensure >=1.0.0 and import correct name.

error YAMLError: while scanning a simple key ↓

cause Docstring YAML indentation is inconsistent or uses tabs instead of spaces.

fix

Use consistent spaces (2 or 4) for indentation. Avoid tabs.

Warnings

breaking Python 3.11 support dropped in v3.0.0. Only Python 3.12+ is supported. ↓

fix Upgrade to Python 3.12 or later, or pin to edx-api-doc-tools<3.0.0

deprecated The 'fields' parameter in create_api_doc was deprecated in v2.x and removed in v3.0.0. ↓

fix Remove 'fields' argument; use docstring-based field descriptions instead.

gotcha Docstring format must be exactly YAML with '---' separator. Indentation errors cause silent failures or partial docs. ↓

fix Ensure docstring starts with a line containing only '---' and that YAML is properly indented.

Imports

create_api_doc
wrong
```
from api_doc_tools import create_api_doc
```
correct
```
from edx_api_doc_tools import create_api_doc
```
Package uses underscores not hyphens, and prefix 'edx_' is required

Quickstart

Basic usage of the create_api_doc decorator to generate OpenAPI documentation from docstrings.

from edx_api_doc_tools import create_api_doc

def my_api_view(request):
    """
    GET /api/v1/resource
    Returns a list of resources.
    """
    pass

# Decorator generates OpenAPI spec
@create_api_doc
def documented_view(request):
    """
    ---
    get:
      summary: Get a resource
      responses:
        200:
          description: Success
    """
    pass