openapi.json cannot be delivered after calling an endpoint with a $ref request body

[bene1618]

Problem description

When creating a Connexion app with an OpenAPI spec which uses $ref to reference the request body schema, requesting /openapi.json leads to an error after the endpoint which uses $ref in the specification has been called.

Minimal example

• Install connexion["swagger-ui"] (and uvicorn for serving), and paste the files below.
• Run the app with uvicorn run:app
• Navigate to Swagger UI: http://localhost:8000/ui and confirm that everything looks good
• Call the /greeting endpoint
• Reload Swagger UI, which leads to an error (see below)

Contents of openapi.yaml:

openapi: "3.0.0"
info:
  title: Greeting application
  version: 0.0.1
paths:
  /greeting:
    post:
      operationId: run.post_greeting
      responses:
        '200':
          description: "Greeting response"
          content:
            text/plain:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Test'
components:
  schemas:
    Test:
      type: object
      properties:
        name:
          type: string
          description: A name

Contents of run.py:

from connexion import AsyncApp

app = AsyncApp(__name__)

def post_greeting(body):
    return f"Hello {body['name']}", 200

app.add_api("openapi.yaml")

Error message

connexion.exceptions.InvalidSpecification: {'content': {'application/json': {'schema': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'A name'}}, 'components': {'schemas': {'Test': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'A name'}}}}}}}}} is not valid under any of the given schemas

Failed validating 'oneOf' in schema['properties']['paths']['patternProperties']['^\\/']['patternProperties']['^(get|put|post|delete|options|head|patch|trace)$']['properties']['requestBody']:
    {'oneOf': [{'$ref': '#/definitions/RequestBody'},
               {'$ref': '#/definitions/Reference'}]}

On instance['paths']['/greeting']['post']['requestBody']:
    {'content': {'application/json': {'schema': {'type': 'object',
                                                 'properties': {'name': {'type': 'string',
                                                                         'description': 'A '
                                                                                        'name'}},
                                                 'components': {'schemas': {'Test': {'type': 'object',
                                                                                     'properties': {'name': {'type': 'string',
                                                                                                             'description': 'A '
                                                                                                                            'name'}}}}}}}}}

More details

The issue seems to be that #2002 returns the processed OpenAPI spec, which contains a components key inside the schema, so that the OpenAPI schema validator complains (correctly) about an invalid spec and /openapi.json refuses to deliver the spec. In fact, some testing shows that reverting bb48fb3 fixes the issue.

I'm not really sure but this might be related to the discussion in #1829.

Sample test

Something like the following might work as an integration test with the openapi.yaml from above (I used this for finding bb48fb3; maybe this helps):

from connexion import AsyncApp
from os import path

def post_greeting(body):
    return f"Hello {body['name']}", 200

def test_esoteric_error():
    app = AsyncApp(__name__)
    app.add_api(path.join(path.dirname(__file__), "fixtures/simple/esoteric-error.yaml"))

    client = app.test_client()

    response = client.get("/openapi.json")
    assert response.status_code == 200

    response = client.post("/greeting", data={"name": "XYZ"}, headers={"Content-Type": "application/json"})
    # assert response.status_code == 200 <-- returns Bad Request for some reason I didn't investigate; however it's sufficient to reproduce the error

    response = client.get("/openapi.json")
    assert response.status_code == 200

[skibbi]

I have a similar error - spec validation failing with components appearing out of nowhere alongside properties and type in requestBody - but I don't have a $ref in requestBody, only in responses" So I don't think that the $ref in requestBody is the cause.

[jhuot9]

I have the same problem with the migration to connection 3

[my-master]

Same here. Looks like this was introduced in the latest release. As a workaround, downgrading from connexion==3.2.0 to connexion==3.1.0 resolved it for me.

[mweigel]

Can confirm I've hit this with Connexion 3.2.0 as well. Rolling back to Connexion 3.1.0 fixes it for now.

[M4C4R]

Rolling back to 3.1.0 helped us too with an inconsistent validation failure due to a supposed recursion issue when using $ref.

Failed validating 'oneOf' in schema['properties']['paths']['patternProperties']['^\\/']['patternProperties']['^(get|put|post|delete|options|head|patch|trace)$']['properties']['requestBody']:
    {'oneOf': [{'$ref': '#/definitions/RequestBody'},
               {'$ref': '#/definitions/Reference'}]}

On instance['paths']['/sample']['post']['requestBody']:
{
  "required": True,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "description": "...",
        "properties": {...},
        "components": {
          "parameters": {...},
          "schemas": {...},
          "requestBodies": {
            "Sample": {
              "required": True,
              "content": "<Recursion on dict with id=140649069447936>"
            },
            ...
          },
          "responses": {...}
        }
      }
    }
  }
}

Simplified version of the spec that was used:

openapi: 3.0.0
info:
  title: sample
  version: 0.0.1
paths:
  /sample:
    post:
      operationId: sample
      requestBody:
        $ref: '#/components/requestBodies/Sample'
      responses:
        200:
          $ref: '#/components/responses/Sample'
components:
  schemas:
    Sample:
      type: object
      properties:
        example:
          type: string
  requestBodies:
    Sample:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Sample'
  responses:
    Sample:
      description: Response of sample endpoint
      content:
        application/json:
          schema:
            type: object

[wemcouncil]

I have run into the same issue, rolling back to 3.1.0 fixes the problem. If I have time, I will look into this tomorrow to see if I can find any clues.

[wemcouncil]

In my situation, the (second) spec being validated has changed such the $ref in 'requestBody' in the working (first) validation has been replaced by the full expansion of that requestBody ref / schema. Then the rest of the data structure matches the original working one.

notably, the full expansion also includes the 'components' and 'securitySchemes' sections of my original YAML specification instead of just the schema that defines the requestBody. So yes, some sort of recursion...

the original YAMl is certainly ok, otherwise nothing would ever work.

The spec it is being validated against expects a $ref or a fully compliant RequestBody definition - so something is re-parsing(?) the original YAML file improperly and adding things to the def of the schema used for the requestBody

[alfechner]

We have the same issue. We host our service in a Docker container. Running it locally works fine. The issue only appears when deployed behind our reverse proxy.

[alanbchristie]

Also having this problem with connexion 3.2.0 on Python 3.13.2-slim.

We also always use Vacuum (https://github.com/daveshanley/vacuum) to lint the OpenAPI file in the build process. There are no reported problems and I suspect this connexion error is an error. It also seems to comply with the examples in Swagger's own Describing Responses documentation (https://swagger.io/docs/specification/v3_0/describing-responses/).

The specific area of complaint relates to this block in our OpenAPI YAML file (which also uses a reference in #/components): -

  /version:
    get:
      summary: Gets the Account Server version
      tags:
      - state
      operationId: app.api_state.get_version
      x-semantic-name: getVersion
      security: []
      responses:
        "400":
          description: >
            Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/as_error'
        "401":
          description: >
            No authorisation token provided
        "403":
          description: >
            You're not authorised to use this path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/as_error'
        "200":
          description: >
            The Account Server version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/state_get_version_response'

Workaround

I can also confirm that rolling back to connexion 3.1.0 resolves the issue, so we too are now stuck on 3.1.0.

[mivade]

I also saw this and downgrading to 3.1.0 resolved it. This issue does not instill me with great confidence in this library going forward.