openapi: POST request specs missing in rendered docs

Running the provided example documentation at https://sphinxcontrib-openapi.readthedocs.io/#how-to-use

    post:
      summary: Create an Evidence
      description: |
        Creates a new evidence record in database.
      parameters:
        - name: evidence
          in: body
          schema:
            $ref: '#/definitions/Evidence'
      responses:
        201:
          description: An evidence.
          schema:
            $ref: '#/definitions/Evidence'

renders as: 2019-03-13-094430_3000x1920_scrot

I was also unable to get any description of the body in my own api specs using a parameter: block with in: body, or with the openapi 3.0 requestBody: block. Is there anything I need to configure in order for rendered docs to display a spec of the request body for POST requests? If this is intended let me know, I’m relatively new to writing openapi docs

About this issue

Original URL
State: closed
Created 5 years ago
Comments: 15 (10 by maintainers)

Commits related to this issue

Merge pull request #47 from albert2126/RequestBody Request body is added to rendered docs - see issue #38 — committed to sphinx-contrib/openapi by ikalnytskyi 5 years ago

Most upvoted comments

This pull request resolves it for OpenAPI 3.x:

Request body is missing in rendered docs #47: https://github.com/sphinx-contrib/openapi/pull/47

albert2126 on Jul 31, 2019

Hi @PabloSanchez95 PabloSanchez95,

In reST such cases are common. Ensure that you have an empty line after the markup block. Try to use spaces instead of the tab before “:request:”.

albert2126 on Jun 3, 2020

Thank you guys for the discussion.

As a matter of a fact, an example is not enough in most cases because it often does not show all properties that can be used in a POST or PUT request. This makes a developer to open the YAML file to find the full specification on the required request. The proposed update doesn’t touch the example section. It just adds the request body section. This is how Swagger-UI does.

I’m studying your notes above to improve the code. Thanks, Albert

albert2126 on Aug 13, 2019

I would still ask if there are any reasons that it could not be merged.

Yes, there are. Here’s an incomplete list if you are interested:

No tests. Not even a single one.
Code duplication.
Hardcoded values of Host and Content-Type in rendered HTTP example (while in fact it’s not even an example, but schema).
Bad assumption that a body contains only application/json content that crashes with any other Content-Type value.

Besides, I still do not understand why are you so oppose using :examples: option? Does it break some use case for you? Can you please elaborate on this? Because I finally found some time to work on this, and your use case may help me to understand better what’s broken and how can I fix it.

ikalnytskyi on Aug 13, 2019

I asked this in #47, but I’ll repeat this question here too. Is this ticket about what’s called :examples: on our docs? Because it looks so. :examples: actuall generates an example snippet based on requestBody. It’s turned off by default because in my opinion, it does too much and lacks some testing. I’m going to work on this and improve it in near future.

ikalnytskyi on Aug 11, 2019