# aws-flask-swagger-ui
Simple Flask blueprint for adding [Swagger UI](https://github.com/swagger-api/swagger-ui) to your flask application.
Including a WSGI adapter for [AWS API Gateway/Lambda Proxy Integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-set-up-simple-proxy.html) 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](./aws_flask_swagger_ui/dist/VERSION)
## Installation
`pip install aws-flask-swagger-ui`
## Usage
Simple usage example is shown below for more options check the file [extend examples](./example.py):
```python
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](https://itnext.io/how-to-easily-create-a-http-301-redirection-with-aws-api-gateway-2bf2874ef3f2).
### 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](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/
## Configuration
The blueprint supports overloading all Swagger UI configuration options that can be JSON serialized.
See [swagger-ui configuration](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters) for options.
Plugins and function parameters are not supported at this time.
OAuth2 parameters can be found at [swagger-ui oauth2](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md).
## License
This library is licensed under the [Apache 2.0 License](./LICENSE).
## Test
- Clone the repo and run pytest
```bash
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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tb102122/aws_flask_swagger_ui",
"name": "aws-flask-swagger-ui",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "flask aws amazon lambda swagger",
"author": "Tobias Bruckert",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/66/fd/bd65b23776cea111664cc22177865105b49de40eaa74085fa65d1a0a6491/aws-flask-swagger-ui-1.1.6.tar.gz",
"platform": null,
"description": "# aws-flask-swagger-ui\n\n\n\n\nSimple Flask blueprint for adding [Swagger UI](https://github.com/swagger-api/swagger-ui) to your flask application.\nIncluding a WSGI adapter for [AWS API Gateway/Lambda Proxy Integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-set-up-simple-proxy.html) 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.\n\nIncluded Swagger UI version: [see here](./aws_flask_swagger_ui/dist/VERSION)\n\n## Installation\n\n`pip install aws-flask-swagger-ui`\n\n## Usage\n\nSimple usage example is shown below for more options check the file [extend examples](./example.py):\n\n```python\nfrom flask import Flask\nfrom aws_flask_swagger_ui import get_swaggerui_blueprint, flask_ui_response\n\napp = Flask(__name__)\n\nswaggerui_blueprint = get_swaggerui_blueprint(\n \"/api-doc\",\n aws_gw_config={\n \"exportType\": \"oas30\",\n \"parameters\": {\n \"extensions\": \"integrations\",\n \"extensions\": \"apigateway\",\n \"extensions\": \"authorizers\",\n },\n },\n)\n\napp.register_blueprint(swaggerui_blueprint)\n\n\ndef lambda_handler(event, context):\n return flask_ui_response(app, event, context, base64_content_types={\"image/png\"})\n```\n\n### AWS Gateway Configuration\nhttp://mysite.com = https://restApiId.execute-api.region.amazonaws.com/stage/\n\nIn order that the above example works correctly the Lambda function must be connected as Proxy to the endpoint http://mysite.com/api-doc/ \n\nConfigure 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.\n\nBecause 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](https://itnext.io/how-to-easily-create-a-http-301-redirection-with-aws-api-gateway-2bf2874ef3f2).\n\n### Lambda Test Event\nThe Lambda function must have the permissions to export the API definition!\n\nIf 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](events/) folder.\n\nTo update your test event, click \"Actions\" -> \"Configure test event\".\n\nWithin the Events you need to update the `\"apiId\"` and `\"stage\"` with values for your AWS account.\n\n### Protect documentation with password\nIf you create an environment variable like, SWAGGER_PASSWORD=abc\n\nThen you will need to pass a query parameter in the URL like, http://mysite.com/api-doc/?pass=abc\n\nIf 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/\n\n\n## Configuration\n\nThe blueprint supports overloading all Swagger UI configuration options that can be JSON serialized.\nSee [swagger-ui configuration](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#parameters) for options.\n\nPlugins and function parameters are not supported at this time.\n\nOAuth2 parameters can be found at [swagger-ui oauth2](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md).\n\n## License\n\nThis library is licensed under the [Apache 2.0 License](./LICENSE).\n\n## Test\n- Clone the repo and run pytest\n\n```bash\ngit clone https://github.com/tb102122/aws_flask_swagger_ui.git\npython -m venv virtualenv\nvirtualenv/bin/activate\npip install --upgrade pip, setuptools, wheel\npip install flake8 pytest boto3 pytest-cov\npip install .\nflake8 .\npytest\n```\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Swagger UI Blueprint for Flask on AWS Lambda",
"version": "1.1.6",
"project_urls": {
"Homepage": "https://github.com/tb102122/aws_flask_swagger_ui"
},
"split_keywords": [
"flask",
"aws",
"amazon",
"lambda",
"swagger"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8634fdf6f5284ca99dbf5e34c3a658c4f4091890746b3ef57ccd9861b546cfa7",
"md5": "222ffd01f4a0d4e6c4793574ab309923",
"sha256": "ca5b69c46d4838169cc7d573048b4a360946583152f59948067bf2b756a31b90"
},
"downloads": -1,
"filename": "aws_flask_swagger_ui-1.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "222ffd01f4a0d4e6c4793574ab309923",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 2955552,
"upload_time": "2024-03-20T23:46:27",
"upload_time_iso_8601": "2024-03-20T23:46:27.666048Z",
"url": "https://files.pythonhosted.org/packages/86/34/fdf6f5284ca99dbf5e34c3a658c4f4091890746b3ef57ccd9861b546cfa7/aws_flask_swagger_ui-1.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66fdbd65b23776cea111664cc22177865105b49de40eaa74085fa65d1a0a6491",
"md5": "283d0b8872b79f1aa0637920895bcb38",
"sha256": "e1ec8c66d2d91dadab088f43d1194eb18eb2ddd5971c940503554c8c87aad10a"
},
"downloads": -1,
"filename": "aws-flask-swagger-ui-1.1.6.tar.gz",
"has_sig": false,
"md5_digest": "283d0b8872b79f1aa0637920895bcb38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2932044,
"upload_time": "2024-03-20T23:46:29",
"upload_time_iso_8601": "2024-03-20T23:46:29.350237Z",
"url": "https://files.pythonhosted.org/packages/66/fd/bd65b23776cea111664cc22177865105b49de40eaa74085fa65d1a0a6491/aws-flask-swagger-ui-1.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 23:46:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tb102122",
"github_project": "aws_flask_swagger_ui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "aws-flask-swagger-ui"
}
JSON
