spec-first / connexion

Connexion is a modern Python web framework that makes spec-first and api-first development easy.
https://connexion.readthedocs.io/en/latest/
Apache License 2.0
4.49k stars 762 forks source link

Fix module name in running the app instructions in v3.rst #1948

Open chrisinmtown opened 3 months ago

chrisinmtown commented 3 months ago

Description

I'm trying to migrate from v2 to v3, and started by reading https://connexion.readthedocs.io/en/latest/v3.html

The section "Running the application" shows a file named hello.py with this content:

import connexion

app = connexion.App(__name__)

if __name__ == "__main__":
    app.run()

Then instructs me to issue one of these commands to run the application:

$ uvicorn run:app
$ gunicorn -k uvicorn.workers.UvicornWorker run:app

I think these should read:

$ uvicorn hello:app
$ gunicorn -k uvicorn.workers.UvicornWorker hello:app

Expected behaviour

The app starts with the expected output:

% uvicorn hello:app
INFO:     Started server process [21732]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Actual behaviour

The module "run" is not found:

% uvicorn run:app
ERROR:    Error loading ASGI app. Could not import module "run"

Steps to reproduce

Additional info:

% python --version
Python 3.11.9
% pip show connexion | grep "^Version\:"
Version: 2.14.2

Look, I realize this bug is trivial. Still the complexity of migrating this app is large, and when the very first step doesn't work, it is frustrating.

Thanks for listening.

chrisinmtown commented 3 months ago

Here's the diff of the change I propose:

% git diff v3.rst
diff --git a/docs/v3.rst b/docs/v3.rst
index 260b9e1..9d34526 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::