sphinx-contrib / sphinx-contrib/openapi

Form data not accepted as POST requestBody

Open
#156 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 have a yaml file using OpenAPI 3.0.3. All my POST requests have their requestBody described, and they all use application/x-www-form-urlencoded.

When rendered, none of the POST requests show the request data, even when using :examples:.

Here's an example from my yaml file:

  /login:
    post:
      description: Login and get user info
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
              required:
                - email
                - password
      responses:
        200:
          description: User Info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'

Here's how I am trying to render this:

.. openapi:: /openapi.yaml
   :examples:

Here's what gets rendered on the HTML page:
27 06 2024_shot_15:53:05

So, the response gets shown correctly, but not the requestBody.

Looking at openapi30.py, I see the following

https://github.com/sphinx-contrib/openapi/blob/e62e2986b66465e785a7ebd8905d639f1893dedc/sphinxcontrib/openapi/openapi30.py#L305

It's assuming that the requestBody will always be application/json, but my API uses application/x-www-form-urlencoded.

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 in sphinxcontrib/openapi/openapi30.py around the requestBody handling linked in the issue, and reproduce the behavior with the provided OpenAPI YAML and :examples: option. Trace how the request content type is selected. Done means application/x-www-form-urlencoded request data and examples render for POST operations, as the response data already does.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.