Document how to install prerequisites in examples READMEs

Add server url /openapi to JWT example
Drop outdated `convert_unicode` parameter in Sqlalchemy example
Correct name of module in v3 instructions

Fixes #1948, #1987

docs/v3.rst

@@ -94,11 +94,11 @@ Instead, you need to run the Connexion application using an ASGI server:
 
 .. code-block:: bash
 
-    $ uvicorn run:app
+    $ uvicorn hello:app
 
 .. code-block:: bash
 
-    $ gunicorn -k uvicorn.workers.UvicornWorker run:app
+    $ gunicorn -k uvicorn.workers.UvicornWorker hello:app
 
 .. warning::
 

examples/apikey/README.rst

@@ -1,16 +1,32 @@
-=======================
+===============
 API Key Example
-=======================
+===============
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
-    $ pip install --upgrade connexion[swagger-ui]  # install Connexion from PyPI
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ or
-http://localhost:8080/swagger/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
 
 The hardcoded apikey is `asdf1234567890`.
 

examples/basicauth/README.rst

@@ -2,14 +2,31 @@
 HTTP Basic Auth Example
 =======================
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
     $ pip install --upgrade connexion[swagger-ui]  # install Connexion from PyPI
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ or
-http://localhost:8080/swagger/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
 
 The hardcoded credentials are ``admin:secret`` and ``foo:bar``.

examples/enforcedefaults/README.rst

@@ -10,14 +10,33 @@ Custom Validator Example
 In this example we fill-in non-provided properties with their defaults.
 Validator code is based on example from `python-jsonschema docs`_.
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/v1/ui/ to see the Swagger
-UI. If you send a ``POST`` request with empty body ``{}``, you should receive
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
+
+If you send a ``POST`` request with empty body ``{}``, you should receive
 echo with defaults filled-in.
 
 .. _python-jsonschema docs: https://python-jsonschema.readthedocs.io/en/latest/faq/#why-doesn-t-my-schema-that-has-a-default-property-actually-set-the-default-on-my-instance

examples/frameworks/README.rst

@@ -4,11 +4,30 @@ Framework Examples
 
 This directory contains minimal examples on how to use Connexion with different frameworks.
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
 
 .. code-block:: bash
 
-    $ python hello_{framework}.py
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+    $ pip install -r requirements.txt
+
+Running
+-------
+
+Launch the connexion server with one of these commands:
+
+.. code-block:: bash
+
+    $ python hello_quart.py
+    $ python hello_starlette.py
+
+Now open your browser and view the Swagger UI for these specification files:
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ or
-http://localhost:8080/swagger/ui/ to see the Swagger UI.
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec

examples/helloworld/README.rst

@@ -2,11 +2,28 @@
 Hello World Example
 ===================
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
     $ python hello.py
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ or
-http://localhost:8080/swagger/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec

examples/helloworld_async/README.rst

@@ -2,11 +2,28 @@
 Hello World Example using async App
 ===================================
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
     $ python hello.py
 
-Now open your browser and go to http://localhost:8000/openapi/ui/ or
-http://localhost:8000/swagger/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec

examples/jwt/README.rst

@@ -1,18 +1,36 @@
-=======================
+================
 JWT Auth Example
-=======================
+================
 
 .. note::
 
     jwt is not supported by swagger 2.0: https://swagger.io/docs/specification/2-0/authentication/
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
 
 .. code-block:: bash
 
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
     $ pip install -r requirements.txt
+
+Running
+-------
+
+Launch the connexion server with this command:
+
+.. code-block:: bash
+
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for the specification file:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+
 Use endpoint **/auth** to generate JWT token, copy it, then click **Authorize** button and paste the token.
-Now you can use endpoint **/secret** to check authentication.
+Now you can use endpoint **/secret** to check authentication.

examples/jwt/requirements.txt

@@ -1,3 +1,2 @@
-..[swagger-ui]
 python-jose[cryptography]
 Flask>=0.10.1

examples/jwt/spec/openapi.yaml

@@ -2,6 +2,8 @@ openapi: 3.0.0
 info:
   title: JWT Example
   version: '1.0'
+servers:
+  - url: /openapi
 paths:
   /auth/{user_id}:
     get:

examples/methodresolver/README.rst

@@ -1,11 +1,28 @@
-=====================
+==========================
 MethodViewResolver Example
-=====================
+==========================
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Launch the connexion server with this command:
 
 .. code-block:: bash
 
     $ python app.py
 
-Now open your browser and go to http://localhost:9090/v1.0/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for the specification file:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec

examples/oauth2/README.rst

@@ -5,15 +5,33 @@ OAuth2 Example
 This example demonstrates how to implement a resource server with Connexion.
 The app will lookup OAuth2 Bearer tokens with the given token info function.
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
+
+Start a mock server in the background, then launch the connexion server,
+with these commands:
 
 .. code-block:: bash
 
-    $ pip install --upgrade connexion  # install Connexion from PyPI
     $ python mock_tokeninfo.py &       # start mock in background
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
 
 You can use the hardcoded tokens to request the endpoint:
 

examples/oauth2_local_tokeninfo/README.rst

@@ -5,14 +5,29 @@ OAuth2 Local Validation Example
 This example demonstrates how to implement a resource server with Connexion.
 The app will lookup OAuth2 Bearer tokens in a static map.
 
-Running:
+Preparing
+---------
+
+Create a new virtual environment and install the required libraries
+with these commands:
+
+.. code-block:: bash
+
+    $ python -m venv my-venv
+    $ source my-venv/bin/activate
+    $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0'
+
+Running
+-------
 
 .. code-block:: bash
 
-    $ pip install --upgrade connexion  # install Connexion from PyPI
     $ python app.py
 
-Now open your browser and go to http://localhost:8080/openapi/ui/ to see the Swagger UI.
+Now open your browser and view the Swagger UI for these specification files:
+
+* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec
+* http://localhost:8080/swagger/ui/ for the Swagger 2 spec
 
 You can use the hardcoded tokens to request the endpoint:
 
@@ -21,4 +36,3 @@ You can use the hardcoded tokens to request the endpoint:
     $ curl http://localhost:8080/openapi/secret   # missing authentication
     $ curl -H 'Authorization: Bearer 123' http://localhost:8080/openapi/secret
     $ curl -H 'Authorization: Bearer 456' http://localhost:8080/swagger/secret
-