From 55bdfbaa70a697ebc308f2b46228e72ab0745a2b Mon Sep 17 00:00:00 2001 From: Robbe Sneyders Date: Mon, 6 Nov 2023 18:49:43 +0100 Subject: [PATCH] Improve ASGI server documentation (#1791) Discussions in #1757 indicate that we should document this more clearly. --- docs/quickstart.rst | 10 ++++++++-- docs/v3.rst | 13 +++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 768828676..d2893f259 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -192,15 +192,21 @@ You can run your application using an ASGI server such as `uvicorn`. If you defi .. code-block:: bash + # assuming your application is defined as ``app`` in ``run.py`` $ uvicorn run:app -Or with gunicorn: +Or with gunicorn (which is recommended in production). .. code-block:: bash + # assuming your application is defined as ``app`` in ``run.py`` $ gunicorn -k uvicorn.workers.UvicornWorker run:app -See the `uvicorn documentation`_ for more details. +See the `uvicorn documentation`_ for more details or check this +`overview of available ASGI servers`_ for other options. + +.. _overview of available ASGI servers: https://asgi.readthedocs.io/en/latest/implementations.html#servers. + If you installed connexion using :code:`connexion[uvicorn]`, you can run it using the :code:`run` method. This is only recommended for development: diff --git a/docs/v3.rst b/docs/v3.rst index 84aeb68a6..ad9700936 100644 --- a/docs/v3.rst +++ b/docs/v3.rst @@ -114,6 +114,19 @@ should work, connexion comes with ``uvicorn`` as an extra: pip install connexion[uvicorn] +Check :ref:`quickstart:Running your application` for more details on how to run your application +using an ASGI server. + +.. warning:: + + You can wrap Connexion with the `ASGIMiddleware`_ offered by `a2wsgi`_ to run it with a WSGI + server. You will however lose the benefits offered by ASGI, and performance might be + impacted. You should only use this as a temporary workaround until you can switch to an ASGI + server. + +.. _ASGIMiddleware: https://github.com/abersheeran/a2wsgi#convert-asgi-app-to-wsgi-app +.. _a2wsgi: https://github.com/abersheeran/a2wsgi + Smaller breaking changes ------------------------