This repository has been archived by the owner on Jul 19, 2021. It is now read-only.
forked from spec-first/connexion
-
Notifications
You must be signed in to change notification settings - Fork 0
Add ARCHITECTURE.rst and module docstrings #6
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
Architecture | ||
============ | ||
|
||
This document describes the high-level architecture of Connexion. | ||
|
||
.. image:: docs/images/architecture.png | ||
:width: 800 | ||
:align: center | ||
:alt: Connexion architecture | ||
|
||
Apps | ||
---- | ||
|
||
A Connexion ``App`` or application wraps a specific framework application (currently Flask or | ||
AioHttp) and exposes a standardized interface for users to create and configure their Connexion | ||
application. | ||
|
||
While a Connexion app implements the WSGI interface, it only acts ass a pass-through and doesn't | ||
actually intercept requests and responses. Connexion does all request and response manipulation | ||
by wrapping the user view function in a Connexion ``Operation``. The underlying framework | ||
application handles incoming requests and routes them to the correct Connexion ``Operation``. | ||
|
||
Api | ||
--- | ||
|
||
A connexion ``API`` takes in an OpenAPI specification and translates the operations defined in it to | ||
a set of Connexion ``Operations``. This set of operations is implemented as a framework blueprint | ||
(A `Flask blueprint`_ or framework-specific equivalent), which can be registered on the framework | ||
application. | ||
|
||
For each operation, the ``API`` resolves the user view function to link to the operation, wraps it | ||
with a Connexion ``Operation`` which it configures based on the OpenAPI spec, and finally adds it as | ||
a route on the framework blueprint. | ||
|
||
When the ``API`` is registered on the Connexion ``APP``, the underlying framework blueprint is | ||
registered on the framework app. | ||
|
||
Operations | ||
---------- | ||
|
||
A Connexion ``Operation`` implements an `OpenAPI operation`_, which describes a single API | ||
operation on a path. It wraps the view function linked to the operation with decorators to handle | ||
security, validation, serialization etc. based on the OpenAPI specification, and exposes the result | ||
to be registered as a route on the application. | ||
|
||
These decorators intercept incoming requests and outgoing responses of the operation and allow | ||
Connexion to manipulate them while leaving the routing up to the underlying framework. The split | ||
into separate decorators allows for a clean layered implementation of Connexion functionality. | ||
|
||
The result is equivalent to the following user code, but instead Connexion implements this | ||
automatically based on the OpenAPI spec. | ||
|
||
.. code-block:: python | ||
|
||
@request_response_lifecycle | ||
@secure_endpoint | ||
@validate_inputs | ||
@deserialize_function_inputs | ||
@serialize_function_outputs | ||
@validate_outputs | ||
def user_provided_view_function(): | ||
... | ||
|
||
|
||
Connexion requests and responses | ||
-------------------------------- | ||
|
||
Connexion defines a request and response interface for internal use. The outermost decorator of | ||
the operation casts framework specific requests to ``ConnexionRequests`` and ``ConnexionResponses`` | ||
to framework specific responses. | ||
|
||
.. _Flask blueprint: https://flask.palletsprojects.com/en/2.0.x/blueprints/ | ||
.. _OpenAPI operation: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,7 @@ | ||
""" | ||
This module provides an entrypoint for Connexion's CLI. | ||
""" | ||
|
||
from connexion.cli import main # pragma: no cover | ||
|
||
main() # pragma: no cover |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,16 @@ | ||
""" | ||
This module defines an Connexion APIs. A connexion API takes in an OpenAPI specification and | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo: "an Connexion APIs." |
||
translates the operations defined in it to a set of Connexion Operations. This set of operations | ||
is implemented as a framework blueprint (A Flask blueprint or framework-specific equivalent), | ||
which can be registered on the framework application. | ||
|
||
For each operation, the API resolves the user view function to link to the operation, wraps it | ||
with a Connexion Operation which it configures based on the OpenAPI spec, and finally adds it as | ||
a route on the framework blueprint. | ||
|
||
When the API is registered on the Connexion APP, the underlying framework blueprint is registered | ||
on the framework app. | ||
""" | ||
|
||
|
||
from .abstract import AbstractAPI # NOQA |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,6 @@ | ||
""" | ||
This module defines Connexion applications. A Connexion App wraps a specific framework application | ||
and exposes a standardized interface for users to create and configure their Connexion application. | ||
""" | ||
|
||
from .abstract import AbstractApp # NOQA |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,7 @@ | ||
""" | ||
This module defines a FlaskApp, a Connexion application to wrap an AioHttp application. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "to wrap a Flask application" |
||
""" | ||
|
||
import datetime | ||
import logging | ||
import pathlib | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
""" | ||
This module defines decorators which Connexion uses to wrap user provided view functions. | ||
""" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,7 @@ | ||
# Decorators to change the return type of endpoints | ||
""" | ||
This module defines an view function decorator to validate its responses. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "an view function" --> "a view function" |
||
""" | ||
|
||
import functools | ||
import logging | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,5 @@ | ||
# This is a dummy module for backwards compatability with < v2.0 | ||
""" | ||
This is a dummy module for backwards compatibility with < v2.0. | ||
""" | ||
from .secure import * # noqa | ||
from .swagger2 import * # noqa |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps provide a link to both swagger 2 and OpenAPI 3 operation objects to make it clear both versions are supported?
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operationObject