Add high level documentation for v3

docs/index.rst

@@ -33,6 +33,7 @@ Contents:
    security
    cookbook
    exceptions
+   v3
 
 .. _Flask: http://flask.pocoo.org/
 .. _OpenAPI: https://openapis.org/

docs/v3.rst

@@ -0,0 +1,72 @@
+.. warning::
+
+    Do not use Connexion 3.0 in production yet!
+
+    Connexion 3.0 is currently available in alpha to give users the ability to test it and provide
+    feedback while we further polish the codebase and update the documentation.
+
+Getting started with Connexion 3.0
+==================================
+
+Connexion 3.0 brings some major changes compared to 2.X:
+
+- Aiohttp support has been dropped in favor of ASGI compatibility and an ``AsyncApp`` built on top
+  of Starlette. This means that you can now use connexion with any ASGI-compatible framework.
+- Connexion's functionality has been refactored from a decorator stack to an ASGI middleware stack,
+  providing a pluggable interface.
+- Validation is now pluggable by content type, solving longstanding issues regarding endpoints with
+  multiple content types and providing a pluggable interface.
+
+
+Using stand-alone Connexion
+---------------------------
+
+You can use Connexion as a stand-alone web framework, using one of the available apps:
+
+- The ``FlaskApp``, which is built on top of Flask as known from Connexion 2.X.
+- The ``AsyncApp``, which is built on top of starlette and provides native asynchronous functionality.
+
+If you don't require compatibility with the Flask ecosystem, we recommend to use the ``AsyncApp``,
+even when writing mostly synchronous code.
+
+Using Connexion with ASGI or WSGI frameworks
+--------------------------------------------
+
+If you want to leverage Connexion functionality with third party ASGI frameworks, you can use the
+``ConnexionMiddleware`` and wrap it around a third party application.
+
+This provides all Connexion functionality except for automatic routing, automatic parameter injection,
+and response serialization. You can add some of this functionality using ``Decorators`` provided by
+Connexion:
+
+- ``FlaskDecorator``: provides automatic parameter injection and response serialization for Flask
+  applications.
+- ``ASGIDecorator``: provides automatic parameter injection for ASGI applications. Note that this
+  decorator injects Starlette datastructures (such as ``UploadFile``).
+- ``StarletteDecorator``: provides automatic parameter injection and response serialization for
+  Starlette applications.
+
+For examples, see https://github.com/spec-first/connexion/tree/main/examples/frameworks.
+
+ASGI Server
+-----------
+
+Connexion 3.0 needs to be run using an ASGI server instead of a WSGI server. While any ASGI server
+should work, connexion comes with ``uvicorn`` as an extra:
+
+.. code-block:: bash
+
+    pip install connexion[uvicorn]
+
+Smaller breaking changes
+------------------------
+
+- The ``options`` argument has been renamed to ``swagger_ui_options``
+- The ``uri_parser_class`` is now passed to the ``App`` or its ``add_api()`` method directly
+  instead of via the ``options`` argument.
+- Drop Flask 1.X support and support Flask 2.X async routes
+- Drop Python 3.6 (and add Python 3.10) support
+- ``connexion.request`` is now a Starlette ``Request`` instead of a Flask ``Request``
+- Route priority changed. The most specific route should now be defined first in the specification.
+- We no longer guess a content type for response serialization if multiple are defined in the spec.
+  We do take into account returned headers.