LukeParke/connexion
1
0
Fork 0
mirror of https://github.com/LukeHagar/connexion.git synced 2025-12-06 04:19:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove cookbook docs and sort index better (#1765)

Browse Source 
Contributes to #1531
This commit is contained in:
Robbe Sneyders
2023-10-30 20:54:59 +01:00
committed by GitHub
parent 99c7a13b53
commit 17aa31a7ab
3 changed files with 48 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
docs/cookbook.rst
View File

@@ -1,151 +0,0 @@
Connexion Cookbook
==================
This section aims to be a cookbook of possible solutions for specific
use cases of Connexion.
Wildcard path parameters
------------------------
Path parameters cannot contain slashes by default, but sometimes it's useful
to have a path parameter which takes the full remainder of the HTTP path
including slashes, e.g. to allow parsing "my/deep/path" from
"/pages/my/deep/path". Connexion supports parsing such path remainders
by using ``format: path``:
.. code-block:: yaml
paths:
/pages/{path}:
get:
# (...)
parameters:
- name: "path"
in: path
description: "Remainder of path, including slashes."
schema:
type: string
format: path
Custom type format
------------------
It is possible to define custom type formats that are going to be used
by the Connexion payload validation on request parameters and response
payloads of your API.
Let's say your API deals with Products and you want to define a field
`price_label` that has a "money" format value. You can create a format
checker function and register that to be used to validate values of
the "money" format.
Example of a possible schema of Product having an attribute with
"money" format that would be defined in your OpenAPI specification:
.. code-block:: yaml
type: object
properties:
title:
type: string
price_label:
type: string
format: money
Then we create a format checker function for that type of value:
.. code-block:: python
import re
MONEY_RE = re.compile('^\$\s*\d+(\.\d\d)?')
def is_money(val):
if not isinstance(val, str):
return True
return MONEY_RE.match(val)
The format checker function is expected to return `True` when the
value matches the expected format and return `False` when it
doesn't. Also is important to verify if the type of the value you are
trying to validate is compatible with the format. In our example we
check if the `val` is of type "string" before performing any further
checking.
The final step to make it work is registering our `is_money` function
to the format "money" in json_schema library. For that, we can use the
draft4 format checker decorator.
.. code-block:: python
from jsonschema import draft4_format_checker
@draft4_format_checker.checks('money')
def is_money(val):
...
This is all you need to have validation for that format in your
Connexion application. Keep in mind that the format checkers should be
defined and registered before you run your application server. A full
example can be found at
https://gist.github.com/rafaelcaricio/6e67286a522f747405a7299e6843cd93
CORS Support
------------
CORS_ (Cross-origin resource sharing) is not built into Connexion, but you can use the `flask-cors`_ library
to set CORS headers:
.. code-block:: python
import connexion
from flask_cors import CORS
app = connexion.FlaskApp(__name__)
app.add_api('swagger.yaml')
# add CORS support
CORS(app.app)
app.run(port=8080)
.. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing
.. _flask-cors: https://flask-cors.readthedocs.io/
Logging
------------
You can customize logging accessing the `_flask-logger` directly
or configuring the logger via dictConfig.
Remember that you should configure logging for your project as soon
as possible when the program starts or you'll get the default configuration.
.. code-block:: python
import connexion
from logging.config import dictConfig
dictConfig({
'version': 1,
'handlers': {
'syslog': {
'class': 'logging.handlers.SysLogHandler'
}
},
'root': {
'handlers': ['syslog']
}
})
app = connexion.FlaskApp(__name__)
app.app.logger.warn("I configured the flask logger!")
app.add_api('swagger.yaml')
app.run(port=8080)
.. _flask-logger: http://flask.pocoo.org/docs/1.0/logging/

3
docs/index.rst
View File

@@ -63,7 +63,6 @@ Documentation
:maxdepth: 2
quickstart
middleware
routing
swagger_ui
request
@@ -72,8 +71,8 @@ Documentation
security
context
lifespan
cookbook
exceptions
middleware
cli
v3

47
docs/validation.rst
View File

@@ -321,5 +321,52 @@ Which you then pass into your application or API as mentioned above.
See our `enforce defaults`_ example for a full example.
Custom type formats
-------------------
It is possible to define custom type formats for validation without adding a custom validator, by
leveraging the ``jsonschema.draft4_format_checker.checks`` decorator.
We can for instance create a custom `money` format.
.. code-block:: python
import re
from jsonschema import draft4_format_checker
MONEY_RE = re.compile('^\$\s*\d+(\.\d\d)?')
@draft4_format_checker.checks('money')
def is_money(val):
if not isinstance(val, str):
return True
return MONEY_RE.match(val)
Which you can then use in your openAPI specification:
.. code-block:: yaml
type: object
properties:
title:
type: string
price_label:
type: string
format: money
The format checker function is expected to return ``True`` when the
value matches the expected format and return ``False`` when it
doesn't. Also is important to verify if the type of the value you are
trying to validate is compatible with the format. In our example we
check if the ``val`` is of type "string" before performing any further
checking.
.. note::
Keep in mind that the format checkers should be defined and registered before you run your
application server.
.. _enforce defaults: https://github.com/spec-first/connexion/tree/main/examples/enforcedefaults
.. _jsonschema: https://github.com/python-jsonschema/jsonschema