Skip to content

Document how to install prerequisites in examples READMEs #1993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RobbeSneyders merged 1 commit into from
Dec 4, 2024
Merged

Document how to install prerequisites in examples READMEs #1993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 22 additions & 6 deletions examples/apikey/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.

Expand Down
24 changes: 20 additions & 4 deletions examples/basicauth/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
25 changes: 22 additions & 3 deletions examples/enforcedefaults/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
27 changes: 23 additions & 4 deletions examples/frameworks/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
23 changes: 20 additions & 3 deletions examples/helloworld/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
23 changes: 20 additions & 3 deletions examples/helloworld_async/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
28 changes: 23 additions & 5 deletions examples/jwt/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 0 additions & 2 deletions examples/jwt/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1 @@
..[swagger-ui]
python-jose[cryptography]
Flask>=0.10.1
2 changes: 2 additions & 0 deletions examples/jwt/spec/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ openapi: 3.0.0
info:
title: JWT Example
version: '1.0'
servers:
- url: /openapi
paths:
/auth/{user_id}:
get:
Expand Down
25 changes: 21 additions & 4 deletions examples/methodresolver/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
24 changes: 21 additions & 3 deletions examples/oauth2/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
22 changes: 18 additions & 4 deletions examples/oauth2_local_tokeninfo/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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

Loading