Skip to content

Commit

Permalink
chore(docs): add bedrock agent resolver documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rubenfonseca
rubenfonseca committed Jan 8, 2024
1 parent aacb37d commit b498cc0
Show file tree
Hide file tree
Showing 22 changed files with 680 additions and 68 deletions.
5 changes: 5 additions & 0 deletions docs/core/event_handler/_openapi_customization_intro.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<!-- markdownlint-disable MD041 MD043 -->
In OpenAPI documentation tools like [SwaggerUI](api-gateway.md#enabling-swaggerui), these annotations become readable descriptions, offering a self-explanatory API interface. This reduces boilerplate code while improving functionality and enabling auto-documentation.

???+ note
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).
15 changes: 15 additions & 0 deletions docs/core/event_handler/_openapi_customization_metadata.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<!-- markdownlint-disable MD041 MD043 -->
Defining and customizing OpenAPI metadata gives detailed, top-level information about your API. Here's the method to set and tailor this metadata:

| Field Name | Type | Description |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | `str` | The title for your API. It should be a concise, specific name that can be used to identify the API in documentation or listings. |
| `version` | `str` | The version of the API you are documenting. This could reflect the release iteration of the API and helps clients understand the evolution of the API. |
| `openapi_version` | `str` | Specifies the version of the OpenAPI Specification on which your API is based. For most contemporary APIs, the default value would be `3.0.0` or higher. |
| `summary` | `str` | A short and informative summary that can provide an overview of what the API does. This can be the same as or different from the title but should add context or information. |
| `description` | `str` | A verbose description that can include Markdown formatting, providing a full explanation of the API's purpose, functionalities, and general usage instructions. |
| `tags` | `List[str]` | A collection of tags that categorize endpoints for better organization and navigation within the documentation. This can group endpoints by their functionality or other criteria. |
| `servers` | `List[Server]` | An array of Server objects, which specify the URL to the server and a description for its environment (production, staging, development, etc.), providing connectivity information. |
| `terms_of_service` | `str` | A URL that points to the terms of service for your API. This could provide legal information and user responsibilities related to the usage of the API. |
| `contact` | `Contact` | A Contact object containing contact details of the organization or individuals maintaining the API. This may include fields such as name, URL, and email. |
| `license_info` | `License` | A License object providing the license details for the API, typically including the name of the license and the URL to the full license text. |
14 changes: 14 additions & 0 deletions docs/core/event_handler/_openapi_customization_operations.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<!-- markdownlint-disable MD041 MD043 -->
Customize your API endpoints by adding metadata to endpoint definitions. This provides descriptive documentation for API consumers and gives extra instructions to the framework.

Here's a breakdown of various customizable fields:

| Field Name | Type | Description |
| ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary` | `str` | A concise overview of the main functionality of the endpoint. This brief introduction is usually displayed in autogenerated API documentation and helps consumers quickly understand what the endpoint does. |
| `description` | `str` | A more detailed explanation of the endpoint, which can include information about the operation's behavior, including side effects, error states, and other operational guidelines. |
| `responses` | `Dict[int, Dict[str, Any]]` | A dictionary that maps each HTTP status code to a Response Object as defined by the [OpenAPI Specification](https://swagger.io/specification/#response-object). This allows you to describe expected responses, including default or error messages, and their corresponding schemas for different status codes. |
| `response_description` | `str` | Provides the default textual description of the response sent by the endpoint when the operation is successful. It is intended to give a human-readable understanding of the result. |
| `tags` | `List[str]` | Tags are a way to categorize and group endpoints within the API documentation. They can help organize the operations by resources or other heuristic. |
| `operation_id` | `str` | A unique identifier for the operation, which can be used for referencing this operation in documentation or code. This ID must be unique across all operations described in the API. |
| `include_in_schema` | `bool` | A boolean value that determines whether or not this operation should be included in the OpenAPI schema. Setting it to `False` can hide the endpoint from generated documentation and schema exports, which might be useful for private or experimental endpoints. |
25 changes: 25 additions & 0 deletions docs/core/event_handler/_openapi_customization_parameters.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!-- markdownlint-disable MD041 MD043 -->
Whenever you use OpenAPI parameters to validate [query strings](api_gateway.md#validating-query-strings) or [path parameters](api_gateway.md#validating-path-parameters), you can enhance validation and OpenAPI documentation by using any of these parameters:

| Field name | Type | Description |
| --------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alias` | `str` | Alternative name for a field, used when serializing and deserializing data |
| `validation_alias` | `str` | Alternative name for a field during validation (but not serialization) |
| `serialization_alias` | `str` | Alternative name for a field during serialization (but not during validation) |
| `description` | `str` | Human-readable description |
| `gt` | `float` | Greater than. If set, value must be greater than this. Only applicable to numbers |
| `ge` | `float` | Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers |
| `lt` | `float` | Less than. If set, value must be less than this. Only applicable to numbers |
| `le` | `float` | Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers |
| `min_length` | `int` | Minimum length for strings |
| `max_length` | `int` | Maximum length for strings |
| `pattern` | `string` | A regular expression that the string must match. |
| `strict` | `bool` | If `True`, strict validation is applied to the field. See [Strict Mode](https://docs.pydantic.dev/latest/concepts/strict_mode/){target"_blank" rel="nofollow"} for details |
| `multiple_of` | `float` | Value must be a multiple of this. Only applicable to numbers |
| `allow_inf_nan` | `bool` | Allow `inf`, `-inf`, `nan`. Only applicable to numbers |
| `max_digits` | `int` | Maximum number of allow digits for strings |
| `decimal_places` | `int` | Maximum number of decimal places allowed for numbers |
| `examples` | `List\[Any\]` | List of examples of the field |
| `deprecated` | `bool` | Marks the field as deprecated |
| `include_in_schema` | `bool` | If `False` the field will not be part of the exported OpenAPI schema |
| `json_schema_extra` | `JsonDict` | Any additional JSON schema data for the schema property |
5 changes: 5 additions & 0 deletions docs/core/event_handler/_openapi_customization_swagger.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<!-- markdownlint-disable MD041 MD043 -->
???+note "Customizing the Swagger metadata"
The `enable_swagger` method accepts the same metadata as described at [Customizing OpenAPI metadata](api_gateway.md#customizing-openapi-metadata).

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.
10 changes: 10 additions & 0 deletions docs/core/event_handler/_swagger_ui.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<!-- markdownlint-disable MD041 MD043 -->
Behind the scenes, the [data validation](api_gateway.md#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.

There are some important **caveats** that you should know before enabling it:

| Caveat | Description |
| ------------------------------------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Swagger UI is **publicly accessible by default** | When using `enable_swagger` method, you can [protect sensitive API endpoints by implementing a custom middleware](api_gateway.md#customizing-swagger-ui) using your preferred authorization mechanism. |
| **No micro-functions support** yet | Swagger UI is enabled on a per resolver instance which will limit its accuracy here. |
| You need to expose **new routes** | You'll need to expose the following paths to Lambda: `/swagger`, `/swagger.css`, `/swagger.js`; ignore if you're routing all paths already. |

0 comments on commit b498cc0

Please sign in to comment.