{"id":21195,"library":"edx-api-doc-tools","title":"edX API Doc Tools","description":"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.","status":"active","version":"3.0.0","language":"python","source_language":"en","source_url":"https://github.com/openedx/api-doc-tools","tags":["edx","api-documentation","openapi"],"install":[{"cmd":"pip install edx-api-doc-tools","lang":"bash","label":"latest stable"}],"dependencies":[],"imports":[{"note":"Package uses underscores not hyphens, and prefix 'edx_' is required","wrong":"from api_doc_tools import create_api_doc","symbol":"create_api_doc","correct":"from edx_api_doc_tools import create_api_doc"}],"quickstart":{"code":"from edx_api_doc_tools import create_api_doc\n\ndef my_api_view(request):\n    \"\"\"\n    GET /api/v1/resource\n    Returns a list of resources.\n    \"\"\"\n    pass\n\n# Decorator generates OpenAPI spec\n@create_api_doc\ndef documented_view(request):\n    \"\"\"\n    ---\n    get:\n      summary: Get a resource\n      responses:\n        200:\n          description: Success\n    \"\"\"\n    pass","lang":"python","description":"Basic usage of the create_api_doc decorator to generate OpenAPI documentation from docstrings."},"warnings":[{"fix":"Upgrade to Python 3.12 or later, or pin to edx-api-doc-tools<3.0.0","message":"Python 3.11 support dropped in v3.0.0. Only Python 3.12+ is supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove 'fields' argument; use docstring-based field descriptions instead.","message":"The 'fields' parameter in create_api_doc was deprecated in v2.x and removed in v3.0.0.","severity":"deprecated","affected_versions":">=2.0.0,<3.0.0"},{"fix":"Ensure docstring starts with a line containing only '---' and that YAML is properly indented.","message":"Docstring format must be exactly YAML with '---' separator. Indentation errors cause silent failures or partial docs.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install and import as 'edx_api_doc_tools' (underscores, no hyphens).","cause":"Incorrect import path; missing 'edx_' prefix or using hyphens.","error":"ModuleNotFoundError: No module named 'api_doc_tools'"},{"fix":"Check installed version: pip show edx-api-doc-tools. Ensure >=1.0.0 and import correct name.","cause":"Older version (<1.0?) or typo in function name.","error":"AttributeError: module 'edx_api_doc_tools' has no attribute 'create_api_doc'"},{"fix":"Use consistent spaces (2 or 4) for indentation. Avoid tabs.","cause":"Docstring YAML indentation is inconsistent or uses tabs instead of spaces.","error":"YAMLError: while scanning a simple key"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}