From 17aa31a7abb43e77ff2d62f91a3dff3a66e4d440 Mon Sep 17 00:00:00 2001 From: Robbe Sneyders Date: Mon, 30 Oct 2023 20:54:59 +0100 Subject: [PATCH] Remove cookbook docs and sort index better (#1765) Contributes to #1531 --- docs/cookbook.rst | 151 -------------------------------------------- docs/index.rst | 3 +- docs/validation.rst | 47 ++++++++++++++ 3 files changed, 48 insertions(+), 153 deletions(-) delete mode 100644 docs/cookbook.rst diff --git a/docs/cookbook.rst b/docs/cookbook.rst deleted file mode 100644 index b628a839e..000000000 --- a/docs/cookbook.rst +++ /dev/null @@ -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/ diff --git a/docs/index.rst b/docs/index.rst index 014b82ba9..52f25b8b6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/validation.rst b/docs/validation.rst index 4e64e34da..7ec3d22fb 100644 --- a/docs/validation.rst +++ b/docs/validation.rst @@ -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 \ No newline at end of file