aws-flask-swagger-ui

Simple Flask blueprint for adding Swagger UI to your flask application. Including a WSGI adapter for AWS API Gateway/Lambda Proxy Integration to allows you to use WSGI-compatible middleware and frameworks like Flask and Django with the AWS API Gateway/Lambda proxy integration for your Swagger documentation.

Included Swagger UI version: see here

Installation

pip install aws-flask-swagger-ui

Usage

Simple usage example is shown below for more options check the file extend examples:

from flask import Flask
from aws_flask_swagger_ui import get_swaggerui_blueprint, flask_ui_response

app = Flask(__name__)

swaggerui_blueprint = get_swaggerui_blueprint(
    "/api-doc",
    aws_gw_config={
        "exportType": "oas30",
        "parameters": {
            "extensions": "integrations",
            "extensions": "apigateway",
            "extensions": "authorizers",
        },
    },
)

app.register_blueprint(swaggerui_blueprint)


def lambda_handler(event, context):
    return flask_ui_response(app, event, context, base64_content_types={"image/png"})

AWS Gateway Configuration

http://mysite.com = https://restApiId.execute-api.region.amazonaws.com/stage/

In order that the above example works correctly the Lambda function must be connected as Proxy to the endpoint http://mysite.com/api-doc/

Configure your API Gateway with a {proxy+} resource with an ANY method. Your "Method Response" should likely include an application/json "Response Body for 200" that uses the Empty model.

Because API Gateway doesn't match the root folder with {proxy+} definition, your default URL should contain index.html. It is suggested to create a mock integration on your path /api-doc to return a 301. (ex: /api-doc => 301 => /api-doc/index.html) Source code based on Terraform to achieve this can be found in this article.

Lambda Test Event

The Lambda function must have the permissions to export the API definition!

If you wish to use the "Test" functionality in Lambda for your function, you will need a "API Gateway AWS Proxy" event. Check the event JSON objects in the events folder.

To update your test event, click "Actions" -> "Configure test event".

Within the Events you need to update the "apiId" and "stage" with values for your AWS account.

Protect documentation with password

If you create an environment variable like, SWAGGER_PASSWORD=abc

Then you will need to pass a query parameter in the URL like, http://mysite.com/api-doc/?pass=abc

If you don't have the environment variable then endpoint is not password protected and you can access it as per normal http://mysite.com/api-doc/

Protect documentation with HTTP Basic Auth

For a real username/password prompt (handled by the browser, and covering the Swagger UI page as well as its static assets), pass basic_auth_credentials or set the SWAGGER_BASIC_AUTH_USER / SWAGGER_BASIC_AUTH_PASSWORD environment variables:

swaggerui_blueprint = get_swaggerui_blueprint(
    "/api-doc",
    aws_gw_config={"exportType": "oas30"},
    basic_auth_credentials=("myuser", "mypassword"),
)

or, without code changes:

export SWAGGER_BASIC_AUTH_USER=myuser
export SWAGGER_BASIC_AUTH_PASSWORD=mypassword

Explicit basic_auth_credentials takes precedence over the environment variables. If neither is set the endpoint is not protected. This is independent of the SWAGGER_PASSWORD query-parameter protection above and both can be combined.

Configuration

The blueprint supports overloading all Swagger UI configuration options that can be JSON serialized. See swagger-ui configuration for options.

Plugins and function parameters are not supported at this time.

OAuth2 parameters can be found at swagger-ui oauth2.

License

This library is licensed under the Apache 2.0 License.

Test

• Clone the repo and run pytest

git clone https://github.com/tb102122/aws_flask_swagger_ui.git
python -m venv virtualenv
virtualenv/bin/activate
pip install --upgrade pip, setuptools, wheel
pip install flake8 pytest boto3 pytest-cov
pip install .
flake8 .
pytest