docs: Improved clarity and formatting within documentation

README.md

@@ -117,7 +117,7 @@ built using either the `AsyncApp` or `FlaskApp`.
 - The `AsyncApp` is a lightweight application with native asynchronous support. Use it if you
   are starting a new project and have no specific reason to use one of the other options.
 
-  ```Python
+  ```python
       from connexion import AsyncApp
 
       app = AsyncApp(__name__)
@@ -155,7 +155,7 @@ The operation described in your specification is automatically linked to your Py
 **run.py**
 
 ```python
-   def post_greeting(name: str, greeting: str):  # Paramaeters are automatically unpacked
+   def post_greeting(name: str, greeting: str):  # Parameters are automatically unpacked
        return f"{greeting} {name}", 200          # Responses are automatically serialized
 
    app.add_api("openapi.yaml")

docs/cli.rst

@@ -1,22 +1,21 @@
 Command-Line Interface
 ======================
-For convenience Connexion provides a command-line interface
-(CLI). This interface aims to be a starting point in developing or
-testing OpenAPI specifications with Connexion.
+For convenience, Connexion provides a command-line interface (CLI). 
+This interface serves as a starting point for developing or testing 
+OpenAPI specifications with Connexion.
 
 Running an OpenAPI specification
 --------------------------------
 
-The subcommand ``run`` of Connexion's CLI makes it easy to run OpenAPI
-specifications directly even before any operation handler function gets
-implemented. This allows you to verify and inspect how your API will
-work with Connexion.
+The ``run`` subcommand of Connexion's CLI makes it easy to run OpenAPI 
+specifications directly, even before any operation handler functions are 
+implemented.
 
 To run your specification, execute in your shell:
 
 .. code-block:: bash
 
-     $ connexion run your_api.yaml --stub
+    $ connexion run your_api.yaml --stub
 
 This command will tell Connexion to run the ``your_api.yaml``
 specification file attaching a stub operation (``--stub``) to the
@@ -32,26 +31,25 @@ Where:
 
 - SPEC_FILE: Your OpenAPI specification file in YAML format. Can also be given
   as a URL, which will be automatically downloaded.
-- BASE_MODULE_PATH (optional): filesystem path where the API endpoints
-  handlers are going to be imported from. In short, where your Python
-  code is saved.
+- BASE_MODULE_PATH (optional): file system path from which the API endpoint 
+  handlers will be imported. In short, where your Python code is saved.
 
 There are more options available for the ``run`` command, for a full
 list run:
 
 .. code-block:: bash
 
-     $ connexion run --help
+    $ connexion run --help
 
 Running a mock server
 ---------------------
 
 You can run a simple server which returns example responses on every request.
 
 The example responses can be defined in the ``examples`` response property of
-the OpenAPI specification. If no examples are specified, and you have installed connexion with the `mock` extra (`pip install connexion[mock]`), an example is generated based on the provided schema.
+the OpenAPI specification. If no examples are specified, and you have installed Connexion with the `mock` extra (``pip install connexion[mock]``), an example is generated based on the provided schema.
 
-Your API specification file is not required to have any ``operationId``.
+Your API specification file does not need to have any ``operationId``.
 
 .. code-block:: bash
 

docs/context.rst

@@ -11,8 +11,12 @@ You can access them by importing them from ``connexion.context``:
     from connexion.context import context, operation, receive, request, scope
     from connexion import request  # alias for connexion.context.request
 
-Note that when trying to access these context variables outside of the request handling flow, or
-without running the ``ContextMiddleware``, the following ``RuntimeError`` will be thrown:
+The ``connexion.request`` is an alias for ``connexion.context.request``, providing a convenient way 
+to access the request object. You only need to use one of these imports to access the request 
+object, using both is not necessary.
+
+When trying to access these context variables outside of the request handling flow, or without 
+running the ``ContextMiddleware``, the following ``RuntimeError`` will be thrown:
 
 .. code-block:: text
 
@@ -80,7 +84,8 @@ scope
 -----
 
 The ASGI scope as received by the ``ContextMiddleware``, thus containing any changes propagated by
-upstream middleware. The ASGI scope is presented as a ``dict``. Please refer to the `ASGI spec`_
+upstream middleware. The ASGI scope is presented as a ``dict``. It includes information about the
+connection, such as HTTP headers, query strings, and server information. Please refer to the `ASGI spec`_
 for more information on its contents.
 
 context.context
@@ -102,10 +107,14 @@ receive
 
 .. warning:: Advanced usage
 
-The receive channel as received by the ``ContextMiddleware``. Note that the receive channel might
-already be read by other parts of Connexion (eg. when accessing the body via the ``Request``, or
-when it is injected into your Python function), and that reading it yourself might make it
-unavailable for those parts of the application.
+The receive channel as received by the ``ContextMiddleware``. The receive channel is an asynchronous
+communication channel used in ASGI applications to receive incoming request data. It allows the
+application to read the request body in a non-blocking manner, which is essential for handling
+concurrent requests efficiently.
+
+Note that the receive channel might already be read by other parts of Connexion (e.g., when accessing
+the body via the ``Request``, or when it is injected into your Python function), and that reading it
+yourself might make it unavailable for those parts of the application.
 
 The receive channel can only be accessed from an ``async`` context and is therefore not relevant
 when using the ``FlaskApp``.

docs/cookbook.rst

@@ -1,7 +1,7 @@
 Connexion Cookbook
 ==================
 
-This page provides recipes with Connexion as an ingredient.
+This section offers practical examples and recipes for using Connexion in your projects.
 
 CORS
 ----
@@ -120,8 +120,9 @@ Starlette. You can add it to your application, ideally in front of the ``Routing
 Reverse Proxy
 -------------
 
-When running behind a reverse proxy with stripped path prefix, you need to configure your
-application to properly handle this.
+When running behind a reverse proxy with a stripped path prefix, you need to configure your
+application to handle this properly. This ensures that your application correctly interprets 
+the original request path.
 
 Single known path prefix
 ''''''''''''''''''''''''

docs/exceptions.rst

@@ -121,8 +121,8 @@ You can register error handlers on:
 
 Default Exception Handling
 --------------------------
-By default connexion exceptions are JSON serialized according to
-`Problem Details for HTTP APIs`_
+By default, Connexion exceptions are JSON serialized according to
+`Problem Details for HTTP APIs`_.
 
 Application can return errors using ``connexion.problem.problem`` or raise exceptions that inherit
 either from ``connexion.ProblemException`` or one of its subclasses to achieve the same behavior.
@@ -150,7 +150,7 @@ Using this, we can rewrite the handler above:
 
 Connexion Exceptions
 --------------------
-There are several exception types in connexion that contain extra information to help you render appropriate
+There are several exception types in Connexion that contain extra information to help you render appropriate
 messages to your user beyond the default description and status code:
 
 .. automodule:: connexion.exceptions

docs/index.rst

@@ -12,7 +12,7 @@
 Welcome to Connexion's documentation!
 =====================================
 
-Connexion is a modern Python web framework that makes spec-first and api-first development easy. You
+Connexion is a modern Python web framework that simplifies spec-first and API-first development. You
 describe your API in an `OpenAPI`_ (or swagger) specification with as much detail as you want and
 Connexion will guarantee that it works as you specified.
 
@@ -29,8 +29,8 @@ Based on your specification, Connexion provides the following functionality:
 * Response validation
 * A Swagger UI console with live documentation and 'try it out' feature
 
-Connexion also helps you write your OpenAPI specification and develop against it by providing a
-command line interface which lets you test and mock your specification.
+Connexion also assists in writing your OpenAPI Specification and developing against it by providing a
+command-line interface for testing and mocking your specification.
 
 .. code-block:: bash
 
@@ -60,8 +60,8 @@ Sponsors help us dedicate time to maintain Connexion. Want to help?
 Why Connexion?
 --------------
 
-Being spec-first is what makes Connexion unique in the Python ecosystem. With Connexion, you write
-your API specification first, and automatically get a lot of functionality. With all other popular
+The spec-first approach is what makes Connexion unique in the Python ecosystem. With Connexion, you 
+write your API specification first, and automatically get a lot of functionality. With all other popular
 Python web frameworks, you write your functionality first, and automatically get your specification.
 
 We choose the spec-first approach because it:
@@ -73,7 +73,7 @@ We choose the spec-first approach because it:
 * Allows for orchestrating multiple layers of your API stack from one contract (eg. API Gateway)
 
 For a more detailed explanation about the benefits of working spec-first, or an overview of helpful
-tooling, have a look at our `recommended resources`_.
+tooling, have a look at our `recommended resources`_ section.
 
 Documentation
 -------------

docs/lifespan.rst

@@ -2,8 +2,8 @@ Lifespan
 ========
 
 You can register lifespan handlers to run code before the app starts, or after it shuts down.
-This ideal for setting up and tearing down database connections or machine learning models for
-instance.
+This is ideal for setting up and tearing down database connections or machine learning models.
+
 
 .. tab-set::
 
@@ -25,7 +25,7 @@ instance.
                 yield {"client": client}
                 client.close()
 
-            def route():
+            def endpoint():
                 """Endpoint function called when receiving a request, you can access the state
                 on the request here."""
                 client = request.state.client
@@ -51,7 +51,7 @@ instance.
                 yield {"client": client}
                 client.close()
 
-            def route():
+            def endpoint():
                 """Endpoint function called when receiving a request, you can access the state
                 on the request here."""
                 client = request.state.client

docs/middleware.rst

@@ -10,13 +10,13 @@ following order:
 
     **ServerErrorMiddleware**, "Returns server errors for any exceptions not caught by the
     ExceptionMiddleware"
-    **ExceptionMiddleware**, Handles exceptions raised by the middleware stack or application
-    **SwaggerUIMiddleware**, Adds a Swagger UI to your application
+    **ExceptionMiddleware**, "Handles exceptions raised by the middleware stack or application"
+    **SwaggerUIMiddleware**, "Adds a Swagger UI to your application"
     **RoutingMiddleware**, "Routes incoming requests to the right operation defined in the
     specification"
     **SecurityMiddleware**, "Checks incoming requests against the security defined in the
     specification"
-    **RequestValidationMiddleware**, Validates the incoming requests against the spec
+    **RequestValidationMiddleware**, "Validates the incoming requests against the spec"
     **ResponseValidationMiddleware**, "Validates the returned responses against the spec, if
     activated"
     **LifespanMiddleware**, "Allows registration of code to run before application start-up or
@@ -191,26 +191,26 @@ Writing custom middleware
 -------------------------
 
 You can add any custom middleware as long as it implements the ASGI interface. To learn how to
-write pure ASGI middleware, please refer to the `documentation of starlette`_.
+write pure ASGI middleware, please refer to the `documentation of Starlette`_.
 
 List of useful middleware
 -------------------------
 
-Starlette provides a bunch of useful middleware such as:
+Starlette provides a variety of useful middleware such as:
 
 * `CORSMiddleware`_
 * `SessionMiddleware`_
 * `HTTPSRedirectMiddleware`_
 * `TrustedHostMiddleware`_
 * `GZipMiddleware`_
 
-Other useful middleware:
+Other useful middleware includes:
 
 * `ProxyHeadersMiddleware`_ by Uvicorn
 * `SentryASGIMiddleware`_ by Sentry
 * `MetricsMiddleware`_ by Prometheus
 
-For more, check the `asgi-middleware topic`_ on github.
+For more, check the `asgi-middleware topic`_ on GitHub.
 
 .. _documentation of starlette: https://www.starlette.io/middleware/#writing-pure-asgi-middleware
 .. _CORSMiddleware: https://www.starlette.io/middleware/#corsmiddleware

docs/quickstart.rst

@@ -15,15 +15,15 @@ Connexion provides 'extras' with optional dependencies to unlock additional feat
 - :code:`flask`: Enables the :code:`FlaskApp` to build applications compatible with the Flask
   ecosystem.
 - :code:`swagger-ui`: Enables a Swagger UI console for your application.
-- :code:`uvicorn`: Enables to run the your application using :code:`app.run()` for
+- :code:`uvicorn`: Enables running your application using :code:`app.run()` for
   development instead of using an external ASGI server.
 
 You can install them as follows:
 
 .. code-block:: bash
 
     $ pip install connexion[<extra>]
-    $ pip install connexion[<extra1>,<extra2>].
+    $ pip install connexion[<extra1>,<extra2>]
 
 Creating your application
 -------------------------
@@ -38,7 +38,7 @@ built using either the :code:`AsyncApp` or :code:`FlaskApp`.
   connexion 2.X or you want to leverage the `Flask` ecosystem.
 - The :code:`ConnexionMiddleware` can be wrapped around any existing ASGI or WSGI application.
   Use it if you already have an application written in a different framework and want to add
-  functionality provided by connexion
+  functionality provided by Connexion.
 
 .. tab-set::
 
@@ -198,7 +198,7 @@ You can run your application using an ASGI server such as `uvicorn`. If you defi
     # assuming your application is defined as ``app`` in ``run.py``
     $ uvicorn run:app
 
-Or with gunicorn (which is recommended in production).
+Or with Gunicorn (which is recommended in production).
 
 .. code-block:: bash
 
@@ -257,7 +257,7 @@ The Swagger UI
 
 If you installed connexion using the :code:`swagger-ui` extra, a Swagger UI is available for each
 API, providing interactive documentation. By default the UI is hosted at :code:`{base_path}/ui/`
-where :code:`base_path`` is the base path of the API.
+where :code:`base_path` is the base path of the API.
 
 **https://{host}/{base_path}/ui/**