diff --git a/docs/v3.rst b/docs/v3.rst index 260b9e197..9d345266e 100644 --- a/docs/v3.rst +++ b/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:: diff --git a/examples/apikey/README.rst b/examples/apikey/README.rst index 98d6e475d..705233067 100644 --- a/examples/apikey/README.rst +++ b/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`. diff --git a/examples/basicauth/README.rst b/examples/basicauth/README.rst index 7f10ffcae..5dfe0a84e 100644 --- a/examples/basicauth/README.rst +++ b/examples/basicauth/README.rst @@ -2,14 +2,30 @@ 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``. diff --git a/examples/enforcedefaults/README.rst b/examples/enforcedefaults/README.rst index 2729001ba..3d51083d3 100644 --- a/examples/enforcedefaults/README.rst +++ b/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[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 diff --git a/examples/frameworks/README.rst b/examples/frameworks/README.rst index b7044bb9f..a7879f3b4 100644 --- a/examples/frameworks/README.rst +++ b/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[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 diff --git a/examples/helloworld/README.rst b/examples/helloworld/README.rst index 44a656108..fbc074146 100644 --- a/examples/helloworld/README.rst +++ b/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 diff --git a/examples/helloworld_async/README.rst b/examples/helloworld_async/README.rst index 9f86cb1cc..b0dd94a70 100644 --- a/examples/helloworld_async/README.rst +++ b/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[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 diff --git a/examples/jwt/README.rst b/examples/jwt/README.rst index cbce38804..6be3b8660 100644 --- a/examples/jwt/README.rst +++ b/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. \ No newline at end of file +Now you can use endpoint **/secret** to check authentication. diff --git a/examples/jwt/requirements.txt b/examples/jwt/requirements.txt index 5ef6e028c..a56b3dabe 100644 --- a/examples/jwt/requirements.txt +++ b/examples/jwt/requirements.txt @@ -1,3 +1,2 @@ -..[swagger-ui] python-jose[cryptography] Flask>=0.10.1 diff --git a/examples/jwt/spec/openapi.yaml b/examples/jwt/spec/openapi.yaml index 71af5cc69..6b026c243 100644 --- a/examples/jwt/spec/openapi.yaml +++ b/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: diff --git a/examples/methodresolver/README.rst b/examples/methodresolver/README.rst index 13677f616..2c0810ab0 100644 --- a/examples/methodresolver/README.rst +++ b/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 diff --git a/examples/oauth2/README.rst b/examples/oauth2/README.rst index 2803a63bc..bc3bc1f44 100644 --- a/examples/oauth2/README.rst +++ b/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: diff --git a/examples/oauth2_local_tokeninfo/README.rst b/examples/oauth2_local_tokeninfo/README.rst index 6880453db..f987e3318 100644 --- a/examples/oauth2_local_tokeninfo/README.rst +++ b/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 - diff --git a/examples/restyresolver/README.rst b/examples/restyresolver/README.rst index 5930326a5..2b4b7edd8 100644 --- a/examples/restyresolver/README.rst +++ b/examples/restyresolver/README.rst @@ -2,11 +2,28 @@ RestyResolver 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 resty.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 diff --git a/examples/reverseproxy/README.rst b/examples/reverseproxy/README.rst index 2f5453ed8..701e0a210 100644 --- a/examples/reverseproxy/README.rst +++ b/examples/reverseproxy/README.rst @@ -28,10 +28,9 @@ You can set the path in three ways: } To run this example, install Connexion from PyPI: - .. code-block:: - $ pip install --upgrade connexion[swagger-ui] + $ pip install 'connexion[flask,swagger-ui,uvicorn]>=3.1.0' and then run it either directly .. code-block:: @@ -45,7 +44,6 @@ or using uvicorn (or another async server): If your proxy server is running at http://localhost:8080/revers_proxied/, you can go to http://localhost:8080/reverse_proxied/openapi/ui/ to see the Swagger UI. - Or you can test this using the ``X-Forwarded-Path`` header to modify the reverse proxy path. For example, note the servers block: @@ -85,4 +83,3 @@ For example, note the servers block: "title" : "Path-Altering Reverse Proxy Example" } } - diff --git a/examples/sqlalchemy/README.rst b/examples/sqlalchemy/README.rst index 2e2f04820..35b20097c 100644 --- a/examples/sqlalchemy/README.rst +++ b/examples/sqlalchemy/README.rst @@ -2,14 +2,36 @@ SQLAlchemy Example ================== +.. note:: + + TODO: Update this example to work with recent (2024) versions of Python and SQLAlchemy. + A simple example of how one might use SQLAlchemy as a backing store for a Connexion based application. -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 these specification files: + +* http://localhost:8080/openapi/ui/ for the OpenAPI 3 spec +* http://localhost:8080/swagger/ui/ for the Swagger 2 spec