Bug: Swagger UI doesn't work correctly when using custom domain name with mapping key

[tlinhart]

Expected Behaviour

I have an API Gateway HTTP API with route /foo. I create a custom domain name for the API my.domain.com and create a mapping with a mapping key api. Thus I access my foo operation with https://my.domain.com/api/foo. In my Lambda function, I create a resolver app and enable swagger on /swagger path:

app = APIGatewayHttpResolver(enable_validation=True)
app.enable_swagger(
    path="/swagger",
    ...
)

I define my operation foo with:

@app.get("/foo", ...)
def foo():
    ...

I can then access the Swagger UI on https://my.domain.com/api/swagger. I also expect:

• I would be able to download the OpenAPI schema via the link under the Swagger UI title, which should be in a form like https://my.domain.com/api/swagger?format=json.
• The operation shown would be like GET /api/foo.
• When I use Try it out feature, it calls the foo operation through https://my.domain.com/api/foo.

Current Behaviour

At the moment, it works like this:

• The OpenAPI schema link has a form like https://my.domain.com/swagger?format=json, i.e. without the mapping key api.
• The operation shown is like GET /foo, i.e. it lacks the mapping key api.
• When I use Try it out feature, it calls the foo operation through https://my.domain.com/foo, i.e. without the mapping key api.

Code snippet

The snippet is shown above.

Possible Solution

The last problem with Try it out can be worked around by defining a server with url="/api". The rest of the issues stays.

Steps to Reproduce

It's described above.

Powertools for AWS Lambda (Python) version

latest

AWS Lambda function runtime

3.11

Packaging format used

PyPi

Debugging logs

No response

[tlinhart]

The first issue with wrong OpenAPI schema link can be solved here replacing:

ui.specActions.updateUrl('{path}?format=json');

with:

ui.specActions.updateUrl(baseUrl + "?format=json");

(to get absolute URL)

or:

ui.specActions.updateUrl(currentUrl.pathname + "?format=json");

(to get relative URL)

[leandrodamascena]

or:

ui.specActions.updateUrl(currentUrl.pathname + "?format=json");

(to get relative URL)

Hi @tlinhart! Thanks for bringing ideas to solve this issue and help with the project! Indeed, using relative URL helps in this case because in this line we update the URL to enable JSON download and it will consider the right path. But we still have the issue when you try to invoke the API using SwaggerUI interface, because we set a default object Server as "/", if not informed, and SwaggerUI take it in consideration to invoke the APIs.
So, in this case and to solve the problem definitively, we need to change the html.py file, but you also need to change the Server configuration to make it work. Something like this:

from aws_lambda_powertools.event_handler.openapi.models import Server

server = Server(url="/api")

app = APIGatewayRestResolver()
app.enable_swagger(path="/swagger",servers=[server])

Do you want to submit a PR to fix this problem? I'm still making some other tests, but I think this is the right direction to go.

Leandro

[tlinhart]

Hi @leandrodamascena, I can prepare a PR to fix the JSON download URL.

When it comes to the other issues, i.e. invoking the API via Swagger UI, what are you suggesting? After reading the OpenAPI spec and thinking about it thoroughly, I'm more and more convinced that it's up to the developer to supply the correct servers to the enable_swagger method.

[leandrodamascena]

Hi @leandrodamascena, I can prepare a PR to fix the JSON download URL.

Thanks @tlinhart! We can make a patch release to fix this.

When it comes to the other issues, i.e. invoking the API via Swagger UI, what are you suggesting? After reading the OpenAPI spec and thinking about it thoroughly, I'm more and more convinced that it's up to the developer to supply the correct servers to the enable_swagger method.

Since this isn't really a bug, it's more about explaining to people how to use Swagger with a different path/custom domain, I think it's worth improving the messaging here:https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/#enabling-swaggerui. While you work to send the PR to fix the JavaScript part, let me think a way to improve this documentation.

[tlinhart]

@leandrodamascena here's the PR – #4930.

Please note that:

• The change is more than just a planned one-liner as after the change, the path parameter of generate_swagger_html became superfluous.
• I removed two tests that merely checked the path based on the stage. As now we only append the format query parameter, these two tests also became superfluous.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.