mirror of
https://github.com/LukeHagar/connexion.git
synced 2025-12-07 12:27:46 +00:00
102 lines
3.3 KiB
ReStructuredText
102 lines
3.3 KiB
ReStructuredText
Request Handling
|
|
================
|
|
Connexion validates incoming requests for conformance with the schemas
|
|
described in swagger specification.
|
|
|
|
Request parameters will be provided to the handler functions as keyword
|
|
arguments if they are included in the function's signature, otherwise body
|
|
parameters can be accessed from ``connexion.request.json`` and query parameters
|
|
can be accessed from ``connexion.request.args``.
|
|
|
|
Request Validation
|
|
------------------
|
|
Both the request body and parameters are validated against the specification,
|
|
using `jsonschema`_.
|
|
|
|
If the request doesn't match the specification connexion will return a 400
|
|
error.
|
|
|
|
Automatic Parameter Handling
|
|
----------------------------
|
|
Connexion automatically maps the parameters defined in your endpoint
|
|
specification to arguments of your Python views as named parameters
|
|
and with value casting whenever possible. All you need to do is define
|
|
the endpoint's parameters with matching names with your views arguments.
|
|
|
|
As example you have a endpoint specified as:
|
|
|
|
.. code-block:: yaml
|
|
|
|
paths:
|
|
/foo:
|
|
get:
|
|
operationId: api.foo_get
|
|
parameters:
|
|
- name: message
|
|
description: Some message.
|
|
in: query
|
|
type: string
|
|
required: true
|
|
|
|
And the view function:
|
|
|
|
.. code-block:: python
|
|
|
|
# api.py file
|
|
|
|
def foo_get(message):
|
|
# do something
|
|
return 'You send the message: {}'.format(message), 200
|
|
|
|
In this example Connexion will automatically identify that your view
|
|
function expects an argument named `message` and will assign the value
|
|
of the endpoint parameter `message` to your view function.
|
|
|
|
Connexion will also use default values if they are provided.
|
|
|
|
.. warning:: Please note that when you have a parameter defined as
|
|
*not* required at your endpoint and your Python view have
|
|
a non-named argument, when you call this endpoint WITHOUT
|
|
the parameter you will get an exception of missing
|
|
positional argument.
|
|
|
|
Type casting
|
|
^^^^^^^^^^^^
|
|
Whenever possible Connexion will try to parse your argument values and
|
|
do type casting to related Python natives values. The current
|
|
available type castings are:
|
|
|
|
+--------------+-------------+
|
|
| Swagger Type | Python Type |
|
|
| | |
|
|
+==============+=============+
|
|
| integer | int |
|
|
+--------------+-------------+
|
|
| string | str |
|
|
+--------------+-------------+
|
|
| number | float |
|
|
+--------------+-------------+
|
|
| boolean | bool |
|
|
+--------------+-------------+
|
|
| array | list |
|
|
+--------------+-------------+
|
|
| object | dict |
|
|
+--------------+-------------+
|
|
|
|
In the Swagger definition if the `array` type is used you can define the
|
|
`collectionFormat` that it should be recognized. Connexion currently
|
|
supports collection formats "pipes" and "csv". The default format is "csv".
|
|
|
|
.. _jsonschema: https://pypi.python.org/pypi/jsonschema
|
|
|
|
Header Parameters
|
|
-----------------
|
|
|
|
Currently header parameters are not passed to the handler functions as parameters. But they can be accessed through the underlying
|
|
``connexion.request.headers`` object which aliases the ``flask.request.headers`` object.
|
|
|
|
.. code-block:: python
|
|
|
|
def index():
|
|
page_number = connexion.request.headers['Page-Number']
|