Swagger UI doesn't work with split specs (connexion 3.3.0)

[gassho]

The problem appears when splitting specs in many openapi.yml files, and adding them with many app.add_api.
All paths are well working.
But when accessing to swagger UI page, no error appears, but it only displays information of last added openapi.yml.

Environment:
Connexion: 3.3.0
Python: 3.10.12

Note:
To make split working, I had to add a unique name for each spec: app.add_api(...., name={unique_name})
Documentation and examples don't explain this.

UPDATE 2025/12/15
Example:
In following file, an API is splitted in Healthchech API and Test API, both with only one distinct path.
test_connexion.py
By executing uvicorn test_connexion:app --host 0.0.0.0 and going on http://127.0.0.1:8000/ui , only information of Healthchech API is displayed, since Healthchech API is the last added API.

As commented, the file includes a version where Test API is added last. If uncommented (and other part commented), then http://127.0.0.1:8000/ui displays only information of Test API.

[chrisinmtown]

Please post a small self-contained example. There are many open issues that refer to problems with swagger and/or with split specifications, including #2095, did you check those to see if your symptom matches what is reported in one of those?

[gassho]

Please post a small self-contained example. There are many open issues that refer to problems with swagger and/or with split specifications, including #2095, did you check those to see if your symptom matches what is reported in one of those?

I checked for another issue on this problem, but I found nothing.
I have began my holidays for 2 weeks, I will add an example for christmas !

[gassho]

I added a self-contained example in the description.

[chrisinmtown]

Thanks for adding the example. When I read "split specs" I understand that to mean the situation where a single API specification is so large that people need to break it into separate files. In that situation, the code calls the add_api method just once, and passes in the top-level OpenAPI spec file. That spec file in turn uses references to other files. There's an example here: https://github.com/spec-first/connexion/tree/main/examples/splitspecs

I don't mean to argue about words tho, sorry. In the issue here, I think you are reporting that the add_api method does not perform as expected when it is called multiple times. I would describe this as "multiple specs". I have not yet searched for a test case that exercises this feature, did you find one?

For what it's worth, the example is not complete; when I run the code and use Swagger to "try it out", I see this error

ResolverProblem(status_code=501, detail='Cannot resolve operationId "healthcheck.HealthView.search"! Import error was "No module named \'healthcheck\'"')

Finally, you reported that Swagger does not work in this situation. Does the server listen and respond on both the endpoints you created by calling add_api? I'm trying to ask if the problem is that the second API is completely absent, or only absent from the Swagger UI?

[chrisinmtown]

I'll attach here a tiny example of a single server supporting two APIs added by calling add_api twice. I tested this example successfully in Connexion v2 and v3. Each Open API spec file uses a different server URL.

I didn't see any server URL in your test application JSON blocks, so (speculating wildly) maybe Connexion uses the default (probably just "/') and the second call overwrites the API registered by the first call? That's a SWAG, and really Connexion should warn if this happens.

Here's file app.py:

import connexion
import importlib.metadata


def get1(identifier):
    return {'identifier': identifier}


def get2(identifier):
    return {'identifier': identifier}


app = connexion.FlaskApp(__name__, specification_dir=".")
app.add_api("api1.yaml")
app.add_api("api2.yaml")


if __name__ == "__main__":
    print('Connexion ' + importlib.metadata.version('connexion'))
    app.run()

Here's file api1.yaml:

openapi: "3.0.0"

info:
  title: API 1
  version: "0.0"
servers:
  - url: /api1

paths:

  /get:
    get:
      parameters:
      - name: identifier
        in: query
        description: ID (integer) or name (string)
        required: true
        schema:
          type: string
      operationId: app.get1
      responses:
        200:
          description: Example data
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string

File api2.yaml is nearly identical, here it is for convenience:

openapi: "3.0.0"

info:
  title: API 2
  version: "0.0"
servers:
  - url: /api2

paths:

  /get:
    get:
      parameters:
      - name: identifier
        in: query
        description: ID (integer) or name (string)
        required: true
        schema:
          type: string
      operationId: app.get2
      responses:
        200:
          description: Example data
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string

[gassho]

When I read "split specs", I understand: split features of the whole spec in many spec files with a file by feature.
In a DRY point of view, I wanted to extract reusable parts of the specs in many servers (ex: healthcheck). I splitted features in many folders, with a folder by feature containing: specific openapi.yml with only feature spec, and dedicated feature code.
I can confirm that it works fine, all paths of all features are working in the servers, except the doc in Swagger UI.

In my simple example, I haven't added the code implementing the paths for simplicity and to be focus on ticket bug. In this example there is only 2 features:

• healthcheck feature with path /health
• test feature with path /test

Example of healthcheck usecase:

In the framework I maintain (HolAdo), I already separated reusable features in separate folders, with possibility to add these features to any server, and I confirm that it works. It is not merged for the moment, thus I haven't added a link as example.

For example with the healthcheck feature, the associated openapi.yml and implementation code are both in a healthcheck folder. In this folder, I added a helper function to simply add healthcheck feature in any server app:

def add_healthcheck_api(app, resolver_error=501, **kwargs):
    here = os.path.abspath(os.path.dirname(__file__))
    package_fullname = os.path.splitext(__name__)[0]
    app.add_api(os.path.join(here, 'openapi.yaml'), 
                resolver=MethodViewResolver(f'{package_fullname}.healthcheck'), pythonic_params=True,
                resolver_error=resolver_error, **kwargs
                )

And it is simple to add healthcheck feature to a server app:

app = connexion.FlaskApp(__name__, pythonic_params=True, swagger_ui_options=swagger_options)

# Add heathcheck
add_healthcheck_api(app, name='healthcheck')

# Add server specific API
app.add_api('openapi.yaml', resolver=MethodViewResolver('server'), pythonic_params=True, resolver_error=501, name='server')

[chrisinmtown]

Thanks for explaining that you are also building a Connexion app from multiple OpenAPI specification files, I didn't understand that at first. I think it would help if you make your standalone example's endpoints work as expected, so anyone who digs into this can focus solely on the underlying behavior that does not work as expected. You also might want to show the specs as separate files, instead of inline JSON, to reflect your use case as accurately as possible.

[gassho]

I love First API approach, thus I use Connexion app to easily add a REST API to microservices.
I doesn't really need Swagger UI documentation, so it doesn't matter for me if this bug is solved rapidely or not.
During january, I will merge in HolAdo the evolution of many microservices with multiple OpenAPI spec files, and then I will add these microservices as examples.

[jhi-9]

I'll attach here a tiny example of a single server supporting two APIs added by calling add_api twice. I tested this example successfully in Connexion v2 and v3. Each Open API spec file uses a different server URL.

I didn't see any server URL in your test application JSON blocks, so (speculating wildly) maybe Connexion uses the default (probably just "/') and the second call overwrites the API registered by the first call? That's a SWAG, and really Connexion should warn if this happens.

Here's file app.py:

import connexion
import importlib.metadata


def get1(identifier):
    return {'identifier': identifier}


def get2(identifier):
    return {'identifier': identifier}


app = connexion.FlaskApp(__name__, specification_dir=".")
app.add_api("api1.yaml")
app.add_api("api2.yaml")


if __name__ == "__main__":
    print('Connexion ' + importlib.metadata.version('connexion'))
    app.run()

Here's file api1.yaml:

openapi: "3.0.0"

info:
  title: API 1
  version: "0.0"
servers:
  - url: /api1

paths:

  /get:
    get:
      parameters:
      - name: identifier
        in: query
        description: ID (integer) or name (string)
        required: true
        schema:
          type: string
      operationId: app.get1
      responses:
        200:
          description: Example data
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string

File api2.yaml is nearly identical, here it is for convenience:

openapi: "3.0.0"

info:
  title: API 2
  version: "0.0"
servers:
  - url: /api2

paths:

  /get:
    get:
      parameters:
      - name: identifier
        in: query
        description: ID (integer) or name (string)
        required: true
        schema:
          type: string
      operationId: app.get2
      responses:
        200:
          description: Example data
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string

If you take this one step further:

app = connexion.FlaskApp(__name__, specification_dir=".")
app.add_api("api1.yaml")
app.add_api("api2.yaml")
app.add_api("api3.yaml")

In my case the second file stopped working. meaning I cannot call the api in the 'api2.yaml'

error: Unexpected error: RuntimeError: Working outside of operation context. Make sure your app is wrapped in a ContextMiddleware and you're processing a request while accessing the context.

I tried adding a 4th, and then the 2nd and 3rd stopped working. same error when calling these apis.

Is there a limitation to only two files?

If I switch the order the first and last always work and the one in the middle gets lost.

Also the swagger UI would only show the last file loaded

happy to open a separate issue for this one if needed

[chrisinmtown]

@jhi-9 wrote:

happy to open a separate issue for this one if needed

It's very difficult to judge from your description whether the problem you describe is different than the original. The connexion add_api method adds each API to an ordered list, so I do not see any limit to the number of APIs. Also you showed an error "Working outside of operation context" which seems very different from the original question. Yes I think you probably should open a separate issue, with a small self-contained example that demonstrates the problem.