sphinx-contrib / sphinx-contrib/openapi

Datetime example field result in build fail for Sphinx

Open
#168 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
126
Forks
88
PR merge metrics
No merged PRs in 30d

Description

I'm trying to use this plugin to integrate an OpenAPI spec in a Sphinx document. However, when using date-time strings in examples I get a build error. An example spec which creates the error would be the following

openapi: 3.0.1
info:
  title: EXAMPLE DATETIME
  version: 1.0.0
paths:
  /test:
    get:
      summary: Test endpoint
      operationId: testId
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResponse'
components:
  schemas:
    TestResponse:
      type: object
      properties:
        TestDate:
          type: string
          format: date-time
      example:
        TestDate: 2000-01-23T04:56:07.000+00:00

Trying to use this file results in:

File "/home/user/.local/share/hatch/env/virtual/docs/0DJxZvn8/docs/lib/python3.12/site-packages/sphinxcontrib/openapi/directive.py", line 56, in run
    return renderer_cls(self.state, self.options).render(spec)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/user/.local/share/hatch/env/virtual/docs/0DJxZvn8/docs/lib/python3.12/site-packages/sphinxcontrib/openapi/renderers/abc.py", line 40, in render
    for line in self.render_restructuredtext_markup(spec):
  File "/home/user/.local/share/hatch/env/virtual/docs/0DJxZvn8/docs/lib/python3.12/site-packages/sphinxcontrib/openapi/renderers/_httpdomain_old.py", line 55, in render_restructuredtext_markup
    yield from openapihttpdomain(spec, **self._options)
  File "/home/user/.local/share/hatch/env/virtual/docs/0DJxZvn8/docs/lib/python3.12/site-packages/sphinxcontrib/openapi/openapi30.py", line 342, in _httpresource
    for line in _example(
  File "/home/user/.local/share/hatch/env/virtual/docs/0DJxZvn8/docs/lib/python3.12/site-packages/sphinxcontrib/openapi/openapi30.py", line 211, in _example
    example['value'] = json.dumps(
                       ^^^^^^^^^^^
  File "/usr/lib/python3.12/json/__init__.py", line 238, in dumps
    **kw).encode(obj)
          ^^^^^^^^^^^
  File "/usr/lib/python3.12/json/encoder.py", line 202, in encode
    chunks = list(chunks)
             ^^^^^^^^^^^^
  File "/usr/lib/python3.12/json/encoder.py", line 432, in _iterencode
    yield from _iterencode_dict(o, _current_indent_level)
  File "/usr/lib/python3.12/json/encoder.py", line 406, in _iterencode_dict
    yield from chunks
  File "/usr/lib/python3.12/json/encoder.py", line 439, in _iterencode
    o = _default(o)
        ^^^^^^^^^^^
  File "/usr/lib/python3.12/json/encoder.py", line 180, in default
    raise TypeError(f'Object of type {o.__class__.__name__} '
TypeError: Object of type datetime is not JSON serializable

Exception occurred:
  File "/usr/lib/python3.12/json/encoder.py", line 180, in default
    raise TypeError(f'Object of type {o.__class__.__name__} '
TypeError: Object of type datetime is not JSON serializable
The full traceback has been saved in /tmp/sphinx-err-vn0id8op.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

If I replace the TestDate entry in the example with 200001-23T04:56:07.000+00:00 the error doesn't get triggered.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with sphinxcontrib/openapi/openapi30.py at the _example function and its json.dumps call, then reproduce the failure with the YAML spec and date-time value from the issue. Check how the example is parsed before serialization. Done means the Sphinx build handles this valid date-time example without the datetime serialization error.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.