mirror of
https://github.com/LukeHagar/connexion.git
synced 2025-12-09 04:19:32 +00:00
98 lines
2.8 KiB
ReStructuredText
98 lines
2.8 KiB
ReStructuredText
Response Handling
|
|
=================
|
|
|
|
Response Serialization
|
|
----------------------
|
|
If the endpoint returns a `Response` object this response will be used as is.
|
|
|
|
Otherwise, and by default and if the specification defines that an endpoint
|
|
produces only JSON, connexion will automatically serialize the return value
|
|
for you and set the right content type in the HTTP header.
|
|
|
|
If the endpoint produces a single non-JSON mimetype then Connexion will
|
|
automatically set the right content type in the HTTP header.
|
|
|
|
Customizing JSON encoder
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Connexion allows you to customize the `JSONEncoder` class in the Flask app
|
|
instance `json_encoder` (`connexion.App:app`). If you wanna reuse the
|
|
Connexion's date-time serialization, inherit your custom encoder from
|
|
`connexion.apps.flask_app.FlaskJSONEncoder`.
|
|
|
|
For more information on the `JSONEncoder`, see the `Flask documentation`_.
|
|
|
|
.. _Flask Documentation: https://flask.palletsprojects.com/en/2.0.x/api/#flask.json.JSONEncoder
|
|
|
|
Returning status codes
|
|
----------------------
|
|
There are two ways of returning a specific status code.
|
|
|
|
One way is to return a `Response` object that will be used unchanged.
|
|
|
|
The other is returning it as a second return value in the response. For example
|
|
|
|
.. code-block:: python
|
|
|
|
def my_endpoint():
|
|
return 'Not Found', 404
|
|
|
|
Returning Headers
|
|
-----------------
|
|
There are two ways to return headers from your endpoints.
|
|
|
|
One way is to return a `Response` object that will be used unchanged.
|
|
|
|
The other is returning a dict with the header values as the third return value
|
|
in the response:
|
|
|
|
For example
|
|
|
|
.. code-block:: python
|
|
|
|
def my_endpoint():
|
|
return 'Not Found', 404, {'x-error': 'not found'}
|
|
|
|
|
|
Response Validation
|
|
-------------------
|
|
While, by default Connexion doesn't validate the responses it's possible to
|
|
do so by opting in when adding the API:
|
|
|
|
.. code-block:: python
|
|
|
|
import connexion
|
|
|
|
app = connexion.FlaskApp(__name__, specification_dir='swagger/')
|
|
app.add_api('my_api.yaml', validate_responses=True)
|
|
app.run(port=8080)
|
|
|
|
This will validate all the responses using `jsonschema` and is specially useful
|
|
during development.
|
|
|
|
|
|
Custom Validator
|
|
-----------------
|
|
|
|
By default, response body contents are validated against OpenAPI schema
|
|
via ``connexion.decorators.response.ResponseValidator``, if you want to change
|
|
the validation, you can override the default class with:
|
|
|
|
.. code-block:: python
|
|
|
|
validator_map = {
|
|
'response': CustomResponseValidator
|
|
}
|
|
app = connexion.FlaskApp(__name__)
|
|
app.add_api('api.yaml', ..., validator_map=validator_map)
|
|
|
|
|
|
Error Handling
|
|
--------------
|
|
By default connexion error messages are JSON serialized according to
|
|
`Problem Details for HTTP APIs`_
|
|
|
|
Application can return errors using ``connexion.problem``.
|
|
|
|
.. _Problem Details for HTTP APIs: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00
|