Skip to content

Commit

Permalink
Update README to include OpenAPI info
Browse files Browse the repository at this point in the history
  • Loading branch information
@smt5541
smt5541 committed Jun 30, 2024
1 parent 02287a3 commit 87d9f4b
Showing 1 changed file with 16 additions and 3 deletions.
19 changes: 16 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@ The `@ValidateParameters()` decorator takes parameters that alter route validati
| Parameter | Type | Default | Description |
|-------------------|----------------------|---------|------------------------------------------------------------------------------------------------------------------------------|
| error_handler | `Optional[Response]` | `None` | Overwrite the output format of generated errors, see [Overwriting Default Errors](#overwriting-default-errors) for more |
| route_deprecated | `bool` | `False` | Marks this Route as deprecated in any generated [API Documentation](#api-documentation) |
| openapi_responses | `Optional[dict]` | `None` | The OpenAPI Responses Object for this route, as a `dict` to be used in any generated [API Documentation](#api-documentation) |
| hide_from_docs | `bool` | `False` | Hide this Route from any generated [API Documentation](#api-documentation) |

#### Overwriting Default Errors
By default, the error messages are returned as a JSON response, with the detailed error in the "error" field. However, this can be edited by passing a custom error function into the `ValidateParameters()` decorator. For example:
Expand Down Expand Up @@ -120,7 +123,7 @@ Validation beyond type-checking can be done by passing arguments into the constr
| `datetime_format` | `str` | `datetime.datetime` | Python datetime format string datetime format string ([datetime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)) |
| `comment` | `str` | All | A string to display as the argument description in any generated documentation |
| `alias` | `str` | All but `FileStorage` | An expected parameter name to receive instead of the function name. |
| `json_schema` | `dict` | `dict` | An expected [JSON Schema](https://json-schema.org) which the dict input must conform to |
| `json_schema` | `dict` | All but `FileStorage` | An expected [JSON Schema](https://json-schema.org) which the dict input must conform to |
| `content_types` | `list[str]` | `FileStorage` | Allowed `Content-Type`s |
| `min_length` | `int` | `FileStorage` | Minimum `Content-Length` for a file |
| `max_length` | `int` | `FileStorage` | Maximum `Content-Length` for a file |
Expand Down Expand Up @@ -148,8 +151,10 @@ def is_odd(val: int):
### API Documentation
Using the data provided through parameters, docstrings, and Flask route registrations, Flask Parameter Validation can generate API Documentation in various formats.
To make this easy to use, it comes with a `Blueprint` and the output and configuration options below:
#### OpenAPI 3.1.0
* `FPV_OPENAPI_BASE: dict`: The base [OpenAPI Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object) that will be populated with a generated [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#paths-object). Must be set to enable the blueprints. Alternatively, the standalone Paths Object can be retrieved anytime through the `generate_openapi_paths_object()` method.

#### Format
#### Non-standard Format
* `FPV_DOCS_SITE_NAME: str`: Your site's name, to be displayed in the page title, default: `Site`
* `FPV_DOCS_CUSTOM_BLOCKS: array`: An array of dicts to display as cards at the top of your documentation, with the (optional) keys:
* `title: Optional[str]`: The title of the card
Expand All @@ -168,6 +173,7 @@ app.register_blueprint(docs_blueprint)
The default blueprint adds two `GET` routes:
* `/`: HTML Page with Bootstrap CSS and toggleable light/dark mode
* `/json`: Non-standard Format JSON Representation of the generated documentation
* `/openapi`: OpenAPI 3.1.0 (JSON) Representation of the generated documentation

The `/json` route yields a response with the following format:
```json
Expand Down Expand Up @@ -224,8 +230,10 @@ Documentation Generated:
If you would like to use your own blueprint, you can get the raw data from the following function:
```py
from flask_parameter_validation.docs_blueprint import get_route_docs
from flask_parameter_validation.docs_blueprint import generate_openapi_paths_object
...
get_route_docs()
generate_openapi_paths_object()
```

###### get_route_docs() return value format
Expand All @@ -238,6 +246,10 @@ This method returns an object with the following structure:
"methods": ["HTTPVerb"],
"docstring": "String, unsanitized of HTML Tags",
"decorators": ["@decorator1", "@decorator2(param)"],
"responses": {
"openapi": "3.1.0",
"description": "See [OpenAPI Spec 3.1.0 Responses Object](https://swagger.io/specification/#response-object)"
},
"args": {
"<Subclass of Parameter this route uses>": [
{
Expand All @@ -246,7 +258,8 @@ This method returns an object with the following structure:
"loc_args": {
"<Name of argument passed to Parameter Subclass>": "Value passed to Argument",
"<Name of another argument passed to Parameter Subclass>": 0
}
},
"deprecated": "bool, whether this parameter is deprecated (only for Route and Query params)"
}
],
"<Another Subclass of Parameter this route uses>": []
Expand Down

0 comments on commit 87d9f4b

Please sign in to comment.