openapi icon indicating copy to clipboard operation
openapi copied to clipboard

Some of the new httpdomain options fail with "unknown option" error

Open stativ opened this issue 8 months ago • 0 comments

When I try to change the response-examples-for option for the new httpdomain renderer, sphinx-build always prints the following error and no examples are generated:

/home/stativ/development/workdir/astra-open-api/index.rst:29: ERROR: Error in "openapi" directive:
unknown option: "response-examples-for".

The same problem happens with the other options that have :None in the option_spec, too.

This happens with the latest sphinx-openapi commit e2c4473480c9299da8f5f1a43958836c5bd833b2 and sphinx 8.2.3

I was able to get it working with this change, but I have no idea whether that is a correct fix:

--- /tmp/openapi/sphinxcontrib/openapi/renderers/_httpdomain.py 2025-05-28 15:25:48.991128250 +0200
+++ .venv/lib/python3.13/site-packages/sphinxcontrib/openapi/renderers/_httpdomain.py   2025-05-28 17:09:13.354386574 +0200
@@ -196,7 +198,7 @@
     option_spec = {
         "markup": functools.partial(directives.choice, values=_markup_converters),
         "http-methods-order": lambda s: s.split(),
-        "response-examples-for": None,
+        "response-examples-for": lambda s: set(s.split()),
         "request-parameters-order": None,
         "example-preference": None,
         "request-example-preference": None,

Now I can configure the examples as:

:response-examples-for: 200 201 202 2XX 400 401 403 404 409 423

A similar change is probably required for other options.

stativ avatar May 28 '25 15:05 stativ