Skip to content

Commit 7f9e6d0

Browse files
leandrodamascenaleandrodamascena
committed
docs: add openapi docs
1 parent 9dca23c commit 7f9e6d0

20 files changed

+815
-340
lines changed

‎aws_lambda_powertools/event_handler/openapi/merge.py‎

Lines changed: 163 additions & 195 deletions
Large diffs are not rendered by default.

‎docs/core/event_handler/api_gateway.md‎

Lines changed: 8 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -485,7 +485,7 @@ This value will override the value of the failed response validation http code s
485485

486486
We use the `Annotated` type to tell the Event Handler that a particular parameter is not only an optional string, but also a query string with constraints.
487487

488-
In the following example, we use a new `Query` OpenAPI type to add [one out of many possible constraints](#customizing-openapi-parameters), which should read as:
488+
In the following example, we use a new `Query` OpenAPI type to add [one out of many possible constraints](openapi.md#customizing-parameters), which should read as:
489489

490490
* `completed` is a query string with a `None` as its default value
491491
* `completed`, when set, should have at minimum 4 characters
@@ -539,7 +539,7 @@ In the following example, we use a new `Query` OpenAPI type to add [one out of m
539539

540540
#### Validating path parameters
541541

542-
Just like we learned in [query string validation](#validating-query-strings), we can use a new `Path` OpenAPI type to [add constraints](#customizing-openapi-parameters).
542+
Just like we learned in [query string validation](#validating-query-strings), we can use a new `Path` OpenAPI type to [add constraints](openapi.md#customizing-parameters).
543543

544544
For example, we could validate that `<todo_id>` dynamic path should be no greater than three digits.
545545

@@ -555,7 +555,7 @@ For example, we could validate that `<todo_id>` dynamic path should be no greate
555555

556556
We use the `Annotated` type to tell the Event Handler that a particular parameter is a header that needs to be validated. Also, we adhere to [HTTP RFC standards](https://www.rfc-editor.org/rfc/rfc7540#section-8.1.2){target="_blank" rel="nofollow"}, which means we treat HTTP headers as case-insensitive.
557557

558-
In the following example, we use a new `Header` OpenAPI type to add [one out of many possible constraints](#customizing-openapi-parameters), which should read as:
558+
In the following example, we use a new `Header` OpenAPI type to add [one out of many possible constraints](openapi.md#customizing-parameters), which should read as:
559559

560560
* `correlation_id` is a header that must be present in the request
561561
* `correlation_id` should have 16 characters
@@ -716,28 +716,15 @@ We provide pre-defined errors for the most popular ones based on [AWS Lambda API
716716

717717
### Enabling SwaggerUI
718718

719-
!!! note "This feature requires [data validation](#data-validation) feature to be enabled."
719+
???+ tip "OpenAPI documentation has moved"
720+
For complete OpenAPI documentation including Swagger UI customization, security schemes, and OpenAPI Merge for micro-functions, see the dedicated [OpenAPI documentation](openapi.md).
720721

721-
Behind the scenes, the [data validation](#data-validation) feature auto-generates an OpenAPI specification from your routes and type annotations. You can use [Swagger UI](https://swagger.io/tools/swagger-ui/){target="_blank" rel="nofollow"} to visualize and interact with your newly auto-documented API.
722-
723-
There are some important **caveats** that you should know before enabling it:
724-
725-
| Caveat | Description |
726-
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
727-
| Swagger UI is **publicly accessible by default** | When using `enable_swagger` method, you can [protect sensitive API endpoints by implementing a custom middleware](#customizing-swagger-ui) using your preferred authorization mechanism. |
728-
| **No micro-functions support** yet | Swagger UI is enabled on a per resolver instance which will limit its accuracy here. |
729-
| You need to expose a **new route** | You'll need to expose the following path to Lambda: `/swagger`; ignore if you're routing this path already. |
730-
| JS and CSS files are **embedded within Swagger HTML** | If you are not using an external CDN to serve Swagger UI assets, we embed JS and CSS directly into the HTML. To enhance performance, please consider enabling the `compress` option to minimize the size of HTTP requests. |
731-
| Authorization data is **lost** on browser close/refresh | Use `enable_swagger(persist_authorization=True)` to persist authorization data, like OAuath 2.0 access tokens. |
722+
Use `enable_swagger()` to serve interactive API documentation:
732723

733724
```python hl_lines="12-13" title="enabling_swagger.py"
734725
--8<-- "examples/event_handler_rest/src/enabling_swagger.py"
735726
```
736727

737-
1. `enable_swagger` creates a route to serve Swagger UI and allows quick customizations. <br><br> You can also include middlewares to protect or enhance the overall experience.
738-
739-
Here's an example of what it looks like by default:
740-
741728
![Swagger UI picture](../../media/swagger.png)
742729

743730
### Custom Domain API Mappings
@@ -1179,128 +1166,8 @@ This will enable full tracebacks errors in the response, print request and respo
11791166

11801167
### OpenAPI
11811168

1182-
When you enable [Data Validation](#data-validation), we use a combination of Pydantic Models and [OpenAPI](https://www.openapis.org/){target="_blank" rel="nofollow"} type annotations to add constraints to your API's parameters.
1183-
1184-
???+ warning "OpenAPI schema version depends on the installed version of Pydantic"
1185-
Pydantic v1 generates [valid OpenAPI 3.0.3 schemas](https://docs.pydantic.dev/1.10/usage/schema/){target="_blank" rel="nofollow"}, and Pydantic v2 generates [valid OpenAPI 3.1.0 schemas](https://docs.pydantic.dev/latest/why/#json-schema){target="_blank" rel="nofollow"}.
1186-
1187-
In OpenAPI documentation tools like [SwaggerUI](#enabling-swaggerui), these annotations become readable descriptions, offering a self-explanatory API interface. This reduces boilerplate code while improving functionality and enabling auto-documentation.
1188-
1189-
???+ note
1190-
We don't have support for files, form data, and header parameters at the moment. If you're interested in this, please [open an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE).
1191-
1192-
#### Customizing OpenAPI parameters
1193-
1194-
--8<-- "docs/core/event_handler/_openapi_customization_parameters.md"
1195-
1196-
#### Customizing API operations
1197-
1198-
--8<-- "docs/core/event_handler/_openapi_customization_operations.md"
1199-
1200-
To implement these customizations, include extra parameters when defining your routes:
1201-
1202-
```python hl_lines="11-20" title="customizing_api_operations.py"
1203-
--8<-- "examples/event_handler_rest/src/customizing_api_operations.py"
1204-
```
1205-
1206-
#### Customizing OpenAPI metadata
1207-
1208-
--8<-- "docs/core/event_handler/_openapi_customization_metadata.md"
1209-
1210-
Include extra parameters when exporting your OpenAPI specification to apply these customizations:
1211-
1212-
=== "customizing_api_metadata.py"
1213-
1214-
```python hl_lines="8-16"
1215-
--8<-- "examples/event_handler_rest/src/customizing_api_metadata.py"
1216-
```
1217-
1218-
#### Customizing Swagger UI
1219-
1220-
???+note "Customizing the Swagger metadata"
1221-
The `enable_swagger` method accepts the same metadata as described at [Customizing OpenAPI metadata](#customizing-openapi-metadata).
1222-
1223-
The Swagger UI appears by default at the `/swagger` path, but you can customize this to serve the documentation from another path and specify the source for Swagger UI assets.
1224-
1225-
Below is an example configuration for serving Swagger UI from a custom path or CDN, with assets like CSS and JavaScript loading from a chosen CDN base URL.
1226-
1227-
=== "customizing_swagger.py"
1228-
1229-
```python hl_lines="10"
1230-
--8<-- "examples/event_handler_rest/src/customizing_swagger.py"
1231-
```
1232-
1233-
=== "customizing_swagger_middlewares.py"
1234-
1235-
A Middleware can handle tasks such as adding security headers, user authentication, or other request processing for serving the Swagger UI.
1236-
1237-
```python hl_lines="7 13-18 21"
1238-
--8<-- "examples/event_handler_rest/src/customizing_swagger_middlewares.py"
1239-
```
1240-
1241-
#### Security schemes
1242-
1243-
???-info "Does Powertools implement any of the security schemes?"
1244-
No. Powertools adds support for generating OpenAPI documentation with [security schemes](https://swagger.io/docs/specification/authentication/), but it doesn't implement any of the security schemes itself, so you must implement the security mechanisms separately.
1245-
1246-
Security schemes are declared at the top-level first. You can reference them globally or on a per path _(operation)_ level. **However**, if you reference security schemes that are not defined at the top-level it will lead to a `SchemaValidationError` _(invalid OpenAPI spec)_.
1247-
1248-
=== "Global OpenAPI security schemes"
1249-
1250-
```python title="security_schemes_global.py" hl_lines="17-27"
1251-
--8<-- "examples/event_handler_rest/src/security_schemes_global.py"
1252-
```
1253-
1254-
1. Using the oauth security scheme defined earlier, scoped to the "admin" role.
1255-
1256-
=== "Per Operation security"
1257-
1258-
```python title="security_schemes_per_operation.py" hl_lines="17-26 30"
1259-
--8<-- "examples/event_handler_rest/src/security_schemes_per_operation.py"
1260-
```
1261-
1262-
1. Using the oauth security scheme defined bellow, scoped to the "admin" role.
1263-
1264-
=== "Global security schemes and optional security per route"
1265-
1266-
```python title="security_schemes_global_and_optional.py" hl_lines="17-26 35"
1267-
--8<-- "examples/event_handler_rest/src/security_schemes_global_and_optional.py"
1268-
```
1269-
1270-
1. To make security optional in a specific route, an empty security requirement ({}) can be included in the array.
1271-
1272-
OpenAPI 3 lets you describe APIs protected using the following security schemes:
1273-
1274-
| Security Scheme | Type | Description |
1275-
| --------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1276-
| [HTTP auth](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml){target="_blank"} | `HTTPBase` | HTTP authentication schemes using the Authorization header (e.g: [Basic auth](https://swagger.io/docs/specification/authentication/basic-authentication/){target="_blank"}, [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/){target="_blank"}) |
1277-
| [API keys](https://swagger.io/docs/specification/authentication/api-keys/){target="_blank"} (e.g: query strings, cookies) | `APIKey` | API keys in headers, query strings or [cookies](https://swagger.io/docs/specification/authentication/cookie-authentication/){target="_blank"}. |
1278-
| [OAuth 2](https://swagger.io/docs/specification/authentication/oauth2/){target="_blank"} | `OAuth2` | Authorization protocol that gives an API client limited access to user data on a web server. |
1279-
| [OpenID Connect Discovery](https://swagger.io/docs/specification/authentication/openid-connect-discovery/){target="_blank"} | `OpenIdConnect` | Identity layer built [on top of the OAuth 2.0 protocol](https://openid.net/developers/how-connect-works/){target="_blank"} and supported by some OAuth 2.0. |
1280-
| [Mutual TLS](https://swagger.io/specification/#security-scheme-object){target="_blank"}. | `MutualTLS` | Client/server certificate mutual authentication scheme. |
1281-
1282-
???-note "Using OAuth2 with the Swagger UI?"
1283-
You can use the `OAuth2Config` option to configure a default OAuth2 app on the generated Swagger UI.
1284-
1285-
```python hl_lines="10 15-18 22"
1286-
--8<-- "examples/event_handler_rest/src/swagger_with_oauth2.py"
1287-
```
1288-
1289-
#### OpenAPI extensions
1290-
1291-
For a better experience when working with Lambda and Amazon API Gateway, customers can define extensions using the `openapi_extensions` parameter. We support defining OpenAPI extensions at the following levels of the OpenAPI JSON Schema: Root, Servers, Operation, and Security Schemes.
1292-
1293-
???+ warning
1294-
We do not support the `x-amazon-apigateway-any-method` and `x-amazon-apigateway-integrations` extensions.
1295-
1296-
```python hl_lines="9 15 25 28" title="Adding OpenAPI extensions"
1297-
--8<-- "examples/event_handler_rest/src/working_with_openapi_extensions.py"
1298-
```
1299-
1300-
1. Server level
1301-
2. Operation level
1302-
3. Security scheme level
1303-
4. Root level
1169+
???+ tip "OpenAPI documentation has moved"
1170+
For complete OpenAPI documentation including customization, security schemes, extensions, and OpenAPI Merge for micro-functions, see the dedicated [OpenAPI documentation](openapi.md).
13041171

13051172
### Custom serializer
13061173

0 commit comments

Comments
 (0)