Metadata-Version: 2.3
Name: sphinx_openapi
Version: 1.0.7
Summary: Sphinx extension for OpenAPI documentation
License: MIT
Author: Xsolla Backend
Author-email: xbe@xsolla.com
Requires-Python: >=3.10
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: orjson (>=3.10.7)
Requires-Dist: requests (>=2.32.3)
Requires-Dist: sphinx (>=7.3.7)
Project-URL: Homepage, https://github.com/Unidocs1/sphinx_openapi
Project-URL: Issues, https://github.com/Unidocs1/sphinx_openapi/issues
Description-Content-Type: text/markdown

# Sphinx Extension: OpenAPI

<!-- Badges go here on the same line; PyPi doesn't support `\` or single-multi-line (it'll stack vertically) -->
[![PyPI](https://img.shields.io/pypi/v/sphinx-openapi)](https://pypi.org/project/sphinx-openapi/) [![PyPI - License](https://img.shields.io/pypi/l/sphinx-openapi)](https://opensource.org/licenses/MIT)

## Description

This Sphinx extension allows for downloading updated OpenAPI json + yaml specs for use with the
[sphinxcontrib.redoc](https://pypi.org/project/sphinxcontrib-redoc/) extension.

## Setup

Add the following to your `conf.py` (includes `redoc` extension setup):

```python
import os
from pathlib import Path

html_context = {}  # This is usually already defined for other themes/extensions
extensions = [
	'sphinx_openapi', 
	'sphinxcontrib.redoc',
]

# -- OpenAPI Shared: Used in multiple extensions --------------------------

openapi_use_xbe_workarounds = False  # (!) True for temp workaround for XBE Doc devs only 

# Downloads json|yaml files to here
openapi_dir_path = Path("_static/specs").resolve().as_posix()
openapi_stop_build_on_error = False  # Generally, only stop if production

# Link here from rst with explicit ".html" ext (!) but NOT from a doctree
openapi_generated_file_posix_path = Path("content/-/api/index")

# -- Extension: sphinx_openapi (OpenAPI Local Download/Updater) -----------
# Used in combination with the sphinxcontrib.redoc extension
# Use OpenAPI ext to download/update → redoc ext to generate

# Define the target json|yaml + path to save the downloaded OpenAPI spec
openapi_spec_url_noext = "https://api.demo.goxbe.cloud/v1/openapi"

# 'json' or 'yaml' (we'll download them both, but generate from only 1)
# (!) Currently, only json is fully functional and, additionally, supports preprocessing in the ext
openapi_file_type = "json"

# Set the config values for the extension
html_context.update({
    "openapi_spec_url_noext": openapi_spec_url_noext,
    "openapi_dir_path": openapi_dir_path,
    "openapi_generated_file_posix_path": openapi_generated_file_posix_path,
    "openapi_file_type": openapi_file_type,
})

# -- Extension: sphinxcontrib.redoc --------------------------------------
# OpenAPI Docgen: Similar to sphinxcontrib-openapi, but +1 column for example responses
# (!) Prereq: OpenAPI Local Download (above)
# Doc | https://sphinxcontrib-redoc.readthedocs.io/en/stable
# Demo | https://sphinxcontrib-redoc.readthedocs.io/en/stable/api/github/

# (!) Works around a critical bug that default grabs old 1.x ver (that !supports OpenAPI 3+)
redoc_uri = "https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"

# Intentional forward/slashes/ for html; eg: "_static/specs/openapi.json"
xbe_spec = Path(openapi_dir_path, "openapi.json")

redoc = [{
    "name": "Xsolla Backend API",
    "page": openapi_generated_file_posix_path,  # content/-/api/index
    "spec": Path("_static/specs/openapi.json"),
    "embed": True,  # Local file only (!) but embed is less powerful
    "template": Path("_templates/redoc.j2"),
    "opts": {
        "lazy-rendering": True,  # Formerly called `lazy`; almost required for giant docs
        "required-props-first": True,  # Useful, (!) but slower
        "native-scrollbars": False,  # Improves perf on big specs when False
        "expand-responses": [],  # "200", "201",
        "suppress-warnings": False,
        "hide-hostname": False,
        "untrusted-spec": False,
    },
}]

print(f'[conf.py::sphinxcontrib.redoc] Build from redoc[0].spec: {redoc[0]["spec"]}')
print(f'[conf.py::sphinxcontrib.redoc] Displaying at redoc[0].page: {redoc[0]["page"]}')
print("")
```

## Requirements

- Python>=3.6
- Sphinx>=7

This may work with older versions, but has not been tested.

## Entry Point

See `setup(app)` definition at `sphinx_openapi.py`.

## Tested in

- Windows 11 via PowerShell 7
- Ubuntu 22.04 via ReadTheDocs (RTD) CI
- Python 3.10~3.12
- Sphinx 7~8

## Notes

- `__init__.py` is required for both external pathing and to treat the directory as a pkg
- **@ XBE Docs devs:** In conf.py, add `openapi_use_xbe_workarounds = True`, for now, for WIP bug workarounds

