{"id":6889,"library":"sphinxcontrib-openapi","title":"OpenAPI (Swagger) Renderer for Sphinx","description":"sphinxcontrib-openapi is a Sphinx extension that renders OpenAPI (formerly Swagger) specifications directly within Sphinx documentation. It leverages `sphinxcontrib-httpdomain` to provide an HTTP domain for describing RESTful HTTP APIs, avoiding the need to re-implement core functionality. It is actively maintained with its latest version 0.9.0 released in February 2026.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/openapi","tags":["sphinx","openapi","swagger","documentation","rest","api","extension"],"install":[{"cmd":"pip install sphinxcontrib-openapi","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generation framework.","package":"Sphinx","optional":false},{"reason":"Provides the HTTP domain for describing RESTful APIs, which sphinxcontrib-openapi builds upon. This is a mandatory dependency.","package":"sphinxcontrib-httpdomain","optional":false}],"imports":[{"note":"Sphinx extensions are activated by adding their string name to the 'extensions' list in `conf.py`, not by direct Python import in document source files.","wrong":"import sphinxcontrib.openapi","symbol":"sphinxcontrib.openapi","correct":"extensions = ['sphinxcontrib.openapi']"}],"quickstart":{"code":"# conf.py\n# Add 'sphinxcontrib.openapi' to your extensions list\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.httpdomain', # Ensure this is also included if not already\n    'sphinxcontrib.openapi'\n]\n\n# docs/api.rst\n# Create a sample OpenAPI spec file at docs/specs/openapi.yml\n# For example:\n# swagger: \"2.0\"\n# info:\n#   title: My API\n#   version: \"1.0.0\"\n# paths:\n#   /greet:\n#     get:\n#       summary: Greet a user\n#       responses:\n#         200:\n#           description: A greeting message\n\n# In your .rst file, use the directive:\n\"\"\"\nAPI Documentation\n=================\n\n.. openapi:: specs/openapi.yml\n   :paths: /greet\n   :examples:\n   :group:\n\"\"\"","lang":"rst","description":"To quickly use `sphinxcontrib-openapi`, first ensure it's added to the `extensions` list in your Sphinx project's `conf.py`. Then, create an OpenAPI specification file (e.g., `openapi.yml`) and use the `.. openapi::` directive in your reStructuredText files, pointing to the spec file. Optional parameters like `:paths:`, `:examples:`, and `:group:` can control what parts of the spec are rendered and how."},"warnings":[{"fix":"Upgrade to the latest version of `sphinxcontrib-openapi`. Review your OpenAPI 3.x spec for any complex or non-standard nesting that might trigger parsing issues.","message":"Older versions of `sphinxcontrib-openapi` (prior to current `0.9.0`) have been reported to struggle with certain structures in OpenAPI 3.0.x specifications, particularly concerning response object nesting, and were more reliably compatible with Swagger 2.0. If encountering rendering issues with OpenAPI 3.x, ensure you are on the latest `sphinxcontrib-openapi` version.","severity":"gotcha","affected_versions":"<=0.7.0 (prior to 0.9.0)"},{"fix":"Ensure `pip install sphinxcontrib-httpdomain` has been run and `'sphinxcontrib.httpdomain'` is in the `extensions` list in `conf.py`.","message":"The `sphinxcontrib-httpdomain` package is a mandatory dependency and must be installed and listed in your `conf.py` `extensions` list alongside `sphinxcontrib.openapi`. Failure to include it will result in `sphinxcontrib-openapi` not functioning correctly as it relies on its HTTP domain definitions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the official documentation for the exact syntax and limitations of directive options. Simplify your OpenAPI spec or try rendering without the problematic options to isolate the issue. Check GitHub issues for known bugs related to your specific rendering problem.","message":"Specific configuration options for the `openapi` directive, such as `:examples:` or filtering `paths`, might not always work as expected for all OpenAPI spec structures or can lead to incomplete rendering. For instance, issues have been reported where schema examples do not show or filtering with multiple paths fails.","severity":"gotcha","affected_versions":"All versions (potential edge cases)"},{"fix":"Check the `sphinxcontrib-openapi` release notes or GitHub repository for compatibility statements with new Sphinx versions before upgrading Sphinx. Pin your Sphinx version if stability is critical.","message":"As a Sphinx extension, `sphinxcontrib-openapi` can be affected by major breaking changes in Sphinx itself. Sphinx releases (e.g., Sphinx 9.0) often introduce incompatible changes to internal APIs that extensions rely on. Always test `sphinxcontrib-openapi` after upgrading Sphinx to a new major version.","severity":"gotcha","affected_versions":"All versions, especially with new major Sphinx releases"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}