{ "info": { "author": "Zalando SE", "author_email": "", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", "Topic :: Software Development :: Libraries :: Application Frameworks" ], "description": "Connexion\n=========\n\n.. image:: https://badges.gitter.im/zalando/connexion.svg\n :alt: Join the chat at https://gitter.im/zalando/connexion\n :target: https://gitter.im/zalando/connexion?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\n.. image:: https://travis-ci.org/zalando/connexion.svg?branch=master\n :target: https://travis-ci.org/zalando/connexion\n :alt: Travis CI build status\n\n.. image:: https://coveralls.io/repos/zalando/connexion/badge.svg?branch=master\n :target: https://coveralls.io/r/zalando/connexion?branch=master\n :alt: Coveralls status\n\n.. image:: https://img.shields.io/pypi/v/connexion.svg\n :target: https://pypi.python.org/pypi/connexion\n :alt: Latest Version\n\n.. image:: https://img.shields.io/pypi/status/connexion.svg\n :target: https://pypi.python.org/pypi/connexion\n :alt: Development Status\n\n.. image:: https://img.shields.io/pypi/pyversions/connexion.svg\n :target: https://pypi.python.org/pypi/connexion\n :alt: Python Versions\n\n.. image:: https://img.shields.io/pypi/l/connexion.svg\n :target: https://github.com/zalando/connexion/blob/master/LICENSE\n :alt: License\n\nConnexion is a framework on top of Flask_ that automagically handles\nHTTP requests based on `OpenAPI 2.0 Specification`_ (formerly known as\nSwagger Spec) of your API described in `YAML format`_. Connexion\nallows you to write a Swagger specification, then maps the\nendpoints to your Python functions; this makes it unique, as many\ntools generate the specification based on your Python\ncode. You can describe your REST API in as much detail as\nyou want; then Connexion guarantees that it will work as\nyou specified.\n\nWe built Connexion this way in order to:\n\n- simplify the development process\n- confirm expectations about what your API will look like\n\nConnexion Features:\n-------------------\n\n- Validates requests and endpoint parameters automatically, based on\n your specification\n- Provides a Web Swagger Console UI so that the users of your API can\n have live documentation and even call your API's endpoints\n through it\n- Handles OAuth 2 token-based authentication\n- Supports API versioning\n- Supports automatic serialization of payloads. If your\n specification defines that an endpoint returns JSON, Connexion will\n automatically serialize the return value for you and set the right\n content type in the HTTP header.\n\nWhy Connexion\n-------------\n\nWith Connexion, you write the spec first. Connexion then calls your Python\ncode, handling the mapping from the specification to the code. This\nincentivizes you to write the specification so that all of your\ndevelopers can understand what your API does, even before you write a\nsingle line of code.\n\nIf multiple teams depend on your APIs, you can use Connexion to easily send them the documentation of your API. This guarantees that your API will follow the specification that you wrote. This is a different process from that offered by frameworks such as Hug_, which generates a specification *after* you've written the code. Some disadvantages of generating specifications based on code is that they often end up lacking details or mix your documentation with the code logic of your application.\n\nOther Sources/Mentions\n----------------------\n\n- Zalando Tech blog post `API First`_\n- Connexion listed on Swagger_'s website\n- Blog post: `Crafting effective Microservices in Python`_\n\nHow to Use\n==========\n\nPrerequisites\n-------------\n\nPython 2.7 or Python 3.4+\n\nInstalling It\n-------------\n\nIn your command line, type:\n\n.. code-block:: bash\n\n $ pip install connexion\n\nRunning It\n----------\n\nPlace your API YAML inside a folder in the root\npath of your application (e.g ``swagger/``). Then run:\n\n.. code-block:: python\n\n import connexion\n\n app = connexion.App(__name__, specification_dir='swagger/')\n app.add_api('my_api.yaml')\n app.run(port=8080)\n\nSee the `Connexion Pet Store Example Application`_ for a sample\nspecification.\n\nNow you're able to run and use Connexion!\n\n\nOAuth 2 Authentication and Authorization\n----------------------------------------\n\nConnexion supports one of the three OAuth 2 handling methods. (See\n\"TODO\" below.) With Connexion, the API security definition **must**\ninclude a 'x-tokenInfoUrl' or 'x-tokenInfoFunc (or set ``TOKENINFO_URL``\nor ``TOKENINFO_FUNC`` env var respectively). 'x-tokenInfoUrl' must contain an\nURL to validate and get the `token information`_ and 'x-tokenInfoFunc must\ncontain a reference to a function used to obtain the token info. When both 'x-tokenInfoUrl'\n and 'x-tokenInfoFunc' are used, Connexion will prioritize the function method. Connexion expects to\nreceive the OAuth token in the ``Authorization`` header field in the\nformat described in `RFC 6750 `_ section 2.1. This aspect\nrepresents a significant difference from the usual OAuth flow.\n\nDynamic Rendering of Your Specification\n---------------------------------------\n\nConnexion uses Jinja2_ to allow specification parameterization through the `arguments` parameter. You can define specification arguments for the application either globally (via the `connexion.App` constructor) or for each specific API (via the `connexion.App#add_api` method):\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/',\n arguments={'global': 'global_value'})\n app.add_api('my_api.yaml', arguments={'api_local': 'local_value'})\n app.run(port=8080)\n\nWhen a value is provided both globally and on the API, the API value will take precedence.\n\nEndpoint Routing to Your Python Views\n-------------------------------------\n\nConnexion uses the ``operationId`` from each `Operation Object`_ to\nidentify which Python function should handle each URL.\n\n**Explicit Routing**:\n\n.. code-block:: yaml\n\n paths:\n /hello_world:\n post:\n operationId: myapp.api.hello_world\n\nIf you provide this path in your specification POST requests to\n``http://MYHOST/hello_world``, it will be handled by the function\n``hello_world`` in the ``myapp.api`` module. Optionally, you can include\n``x-swagger-router-controller`` in your operation definition, making\n``operationId`` relative:\n\n.. code-block:: yaml\n\n paths:\n /hello_world:\n post:\n x-swagger-router-controller: myapp.api\n operationId: hello_world\n\nAutomatic Routing\n-----------------\n\nTo customize this behavior, Connexion can use alternative\n``Resolvers``--for example, ``RestyResolver``. The ``RestyResolver``\nwill compose an ``operationId`` based on the path and HTTP method of\nthe endpoints in your specification:\n\n.. code-block:: python\n\n from connexion.resolver import RestyResolver\n\n app = connexion.App(__name__)\n app.add_api('swagger.yaml', resolver=RestyResolver('api'))\n\n.. code-block:: yaml\n\n paths:\n /:\n get:\n # Implied operationId: api.get\n /foo:\n get:\n # Implied operationId: api.foo.search\n post:\n # Implied operationId: api.foo.post\n\n '/foo/{id}':\n get:\n # Implied operationId: api.foo.get\n put:\n # Implied operationId: api.foo.put\n copy:\n # Implied operationId: api.foo.copy\n delete:\n # Implied operationId: api.foo.delete\n\n``RestyResolver`` will give precedence to any ``operationId`` encountered in the specification. It will also respect\n``x-router-controller``. You can import and extend ``connexion.resolver.Resolver`` to implement your own ``operationId``\n(and function) resolution algorithm.\n\nAutomatic Parameter Handling\n----------------------------\n\nConnexion automatically maps the parameters defined in your endpoint specification to arguments of your Python views as named parameters, and, whenever possible, with value casting. Simply define the endpoint's parameters with the same names as your views arguments.\n\nAs an example, say you have an endpoint specified as:\n\n.. code-block:: yaml\n\n paths:\n /foo:\n get:\n operationId: api.foo_get\n parameters:\n - name: message\n description: Some message.\n in: query\n type: string\n required: true\n\nAnd the view function:\n\n.. code-block:: python\n\n # api.py file\n\n def foo_get(message):\n # do something\n return 'You send the message: {}'.format(message), 200\n\nIn this example, Connexion automatically recognizes that your view\nfunction expects an argument named `message` and assigns the value\nof the endpoint parameter `message` to your view function.\n\n.. warning:: When you define a parameter at your endpoint as *not* required, and your Python view has\n a non-named argument, you will get a \"missing positional argument\" exception whenever you call this endpoint WITHOUT the parameter.\n\nType casting\n^^^^^^^^^^^^\n\nWhenever possible, Connexion will try to parse your argument values and\ndo type casting to related Python native values. The current\navailable type castings are:\n\n+--------------+-------------+\n| Swagger Type | Python Type |\n+==============+=============+\n| integer | int |\n+--------------+-------------+\n| string | str |\n+--------------+-------------+\n| number | float |\n+--------------+-------------+\n| boolean | bool |\n+--------------+-------------+\n| array | list |\n+--------------+-------------+\n| object | dict |\n+--------------+-------------+\n\nIf you use the `array` type In the Swagger definition, you can define the\n`collectionFormat` so that it won't be recognized. Connexion currently\nsupports collection formats \"pipes\" and \"csv\". The default format is \"csv\".\n\nParameter validation\n^^^^^^^^^^^^^^^^^^^^\n\nConnexion can apply strict parameter validation for query and form data\nparameters. When this is enabled, requests that include parameters not defined\nin the swagger spec return a 400 error. You can enable it when adding the API\nto your application:\n\n.. code-block:: python\n\n app.add_api('my_apy.yaml', strict_validation=True)\n\nAPI Versioning and basePath\n---------------------------\n\nYou can also define a ``basePath`` on the top level of the API\nspecification. This is useful for versioned APIs. To serve the\nprevious endpoint from ``http://MYHOST/1.0/hello_world``, type:\n\n.. code-block:: yaml\n\n basePath: /1.0\n\n paths:\n /hello_world:\n post:\n operationId: myapp.api.hello_world\n\nIf you don't want to include the base path in your specification, you\ncan provide it when adding the API to your application:\n\n.. code-block:: python\n\n app.add_api('my_api.yaml', base_path='/1.0')\n\nSwagger JSON\n------------\nConnexion makes the OpenAPI/Swagger specification in JSON format\navailable from ``swagger.json`` in the base path of the API.\n\nYou can disable the Swagger JSON at the application level:\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/',\n swagger_json=False)\n app.add_api('my_api.yaml')\n\nYou can also disable it at the API level:\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/')\n app.add_api('my_api.yaml', swagger_json=False)\n\nHTTPS Support\n-------------\n\nWhen specifying HTTPS as the scheme in the API YAML file, all the URIs\nin the served Swagger UI are HTTPS endpoints. The problem: The default\nserver that runs is a \"normal\" HTTP server. This means that the\nSwagger UI cannot be used to play with the API. What is the correct\nway to start a HTTPS server when using Connexion?\n\nOne way, `described by Flask`_, looks like this:\n\n.. code-block:: python\n\n from OpenSSL import SSL\n context = SSL.Context(SSL.SSLv23_METHOD)\n context.use_privatekey_file('yourserver.key')\n context.use_certificate_file('yourserver.crt')\n\n app.run(host='127.0.0.1', port='12344',\n debug=False/True, ssl_context=context)\n\nHowever, Connexion doesn't provide an ssl_context parameter. This is\nbecause Flask doesn't, either--but it uses `**kwargs` to send the\nparameters to the underlying [werkzeug](http://werkzeug.pocoo.org/) server.\n\nThe Swagger UI Console\n----------------------\n\nThe Swagger UI for an API is available, by default, in\n``{base_path}/ui/`` where ``base_path`` is the base path of the API.\n\nYou can disable the Swagger UI at the application level:\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/',\n swagger_ui=False)\n app.add_api('my_api.yaml')\n\n\nYou can also disable it at the API level:\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/')\n app.add_api('my_api.yaml', swagger_ui=False)\n\nIf necessary, you can explicitly specify the path to the directory with\nswagger-ui to not use the connexion-embedded swagger-ui distro.\nIn order to do this, you should specify the following option:\n\n.. code-block:: python\n\n options = {'swagger_path': '/path/to/swagger_ui/'}\n app = connexion.App(__name__, specification_dir='swagger/', options=options)\n\nMake sure that `swagger_ui/index.html` loads by default local swagger json.\nYou can use the `api_url` jinja variable for this purpose:\n\n.. code-block::\n \n const ui = SwaggerUIBundle({ url: \"{{ api_url }}/swagger.json\"})\n\nServer Backend\n--------------\n\nConnexion uses the default Flask server. For asynchronous\napplications, you can also use Tornado_ as the HTTP server. To do\nthis, set your server to ``tornado``:\n\n.. code-block:: python\n\n import connexion\n\n app = connexion.App(__name__, specification_dir='swagger/')\n app.run(server='tornado', port=8080)\n\nYou can use the Flask WSGI app with any WSGI container, e.g. `using\nFlask with uWSGI`_ (this is common):\n\n.. code-block:: python\n\n app = connexion.App(__name__, specification_dir='swagger/')\n application = app.app # expose global WSGI application object\n\nYou can use the ``aiohttp`` framework as server backend as well:\n\n.. code-block:: python\n\n import connexion\n\n app = connexion.AioHttpApp(__name__, specification_dir='swagger/')\n app.run(port=8080)\n\n**NOTE:** Also check aiohttp handler examples_.\n\nSet up and run the installation code:\n\n.. code-block:: bash\n\n $ sudo pip3 install uwsgi\n $ uwsgi --http :8080 -w app -p 16 # use 16 worker processes\n\nSee the `uWSGI documentation`_ for more information.\n\n.. _using Flask with uWSGI: http://flask.pocoo.org/docs/latest/deploying/uwsgi/\n.. _uWSGI documentation: https://uwsgi-docs.readthedocs.org/\n.. _examples: https://docs.aiohttp.org/en/stable/web.html#handler\n\n\nDocumentation\n=============\nAdditional information is available at `Connexion's Documentation Page`_.\n\nChanges\n=======\n\nA full changelog is maintained on the `GitHub releases page`_.\n\n.. _GitHub releases page: https://github.com/zalando/connexion/releases\n\nContributing to Connexion/TODOs\n===============================\n\nWe welcome your ideas, issues, and pull requests. Just follow the\nusual/standard GitHub practices.\n\nUnless you explicitly state otherwise in advance, any non trivial \ncontribution intentionally submitted for inclusion in this project by you \nto the steward of this repository (Zalando SE, Berlin) shall be under the \nterms and conditions of Apache License 2.0 written below, without any \nadditional copyright information, terms or conditions.\n\nTODOs\n-----\n\n\nIf you'd like to become a more consistent contributor to Connexion, we'd love your help working on\nthese we have a list of `issues where we are looking for contributions`_.\n\nThanks\n===================\n\nWe'd like to thank all of Connexion's contributors for working on this\nproject, and to Swagger/OpenAPI for their support.\n\nLicense\n===================\n\nCopyright 2015 Zalando SE\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n.. _Flask: http://flask.pocoo.org/\n.. _issues waffle board: https://waffle.io/zalando/connexion\n.. _API First: https://tech.zalando.com/blog/on-apis-and-the-zalando-api-guild/\n.. _Hug: https://github.com/timothycrosley/hug\n.. _Swagger: http://swagger.io/open-source-integrations/\n.. _Jinja2: http://jinja.pocoo.org/\n.. _rfc6750: https://tools.ietf.org/html/rfc6750\n.. _OpenAPI 2.0 Specification: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md\n.. _Operation Object: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object\n.. _swager.spec.security_definition: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-definitions-object\n.. _swager.spec.security_requirement: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-requirement-object\n.. _YAML format: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#format\n.. _token information: https://tools.ietf.org/html/rfc6749\n.. _Tornado: http://www.tornadoweb.org/en/stable/\n.. _Connexion Pet Store Example Application: https://github.com/hjacobs/connexion-example\n.. _described by Flask: http://flask.pocoo.org/snippets/111/\n.. _Connexion's Documentation Page: http://connexion.readthedocs.org/en/latest/\n.. _Crafting effective Microservices in Python: http://caricio.com/2016/09/16/crafting-effective-microservices-in-python/\n.. _issues where we are looking for contributions: https://github.com/zalando/connexion/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22\n", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/zalando/connexion", "keywords": "openapi oai swagger rest api oauth flask microservice framework", "license": "Apache License Version 2.0", "maintainer": "", "maintainer_email": "", "name": "connexion-aiohttp", "package_url": "https://pypi.org/project/connexion-aiohttp/", "platform": "", "project_url": "https://pypi.org/project/connexion-aiohttp/", "project_urls": { "Homepage": "https://github.com/zalando/connexion" }, "release_url": "https://pypi.org/project/connexion-aiohttp/1.5/", "requires_dist": null, "requires_python": "", "summary": "Connexion - API first applications with OpenAPI/Swagger and Flask", "version": "1.5" }, "last_serial": 3720199, "releases": { "0.9.0": [ { "comment_text": "", "digests": { "md5": "518989d4199ebb3b8412065d2b85e2b1", "sha256": "22035710b64652628d62f127a465806a110060dd9c1532939fe463a5372a8d59" }, "downloads": -1, "filename": "connexion-aiohttp-0.9.0.tar.gz", "has_sig": false, "md5_digest": "518989d4199ebb3b8412065d2b85e2b1", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 980429, "upload_time": "2018-03-28T20:46:26", "url": "https://files.pythonhosted.org/packages/68/5f/80e45cfb663e3792af799fe04b2c504ec09cc80f69012651bd5acd72d2c2/connexion-aiohttp-0.9.0.tar.gz" } ], "1.4": [ { "comment_text": "", "digests": { "md5": "8133852ce45ca83a2820c72644ede20b", "sha256": "90f899470c0d5cd29b1413aee5afd02378adad95061989f0a8cd1e2dc909db8a" }, "downloads": -1, "filename": "connexion-aiohttp-1.4.tar.gz", "has_sig": false, "md5_digest": "8133852ce45ca83a2820c72644ede20b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 985114, "upload_time": "2018-03-04T01:47:51", "url": "https://files.pythonhosted.org/packages/42/d1/1f021db3ba062beafcb32c4463ad7f1368a6e878249aae135e7bf1016e80/connexion-aiohttp-1.4.tar.gz" } ], "1.5": [ { "comment_text": "", "digests": { "md5": "7267061526bb8a84898ac81f5e5781d7", "sha256": "10623ad83e2cab64bf112d04a676ffe3fef03c7120cebb3f90eac8c560418471" }, "downloads": -1, "filename": "connexion-aiohttp-1.5.tar.gz", "has_sig": false, "md5_digest": "7267061526bb8a84898ac81f5e5781d7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 985263, "upload_time": "2018-03-30T17:19:50", "url": "https://files.pythonhosted.org/packages/60/c7/7774c635d09a2b6216ecd2a39fb5efdf5dd21cbd025f59dd6f49c9ed4872/connexion-aiohttp-1.5.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "7267061526bb8a84898ac81f5e5781d7", "sha256": "10623ad83e2cab64bf112d04a676ffe3fef03c7120cebb3f90eac8c560418471" }, "downloads": -1, "filename": "connexion-aiohttp-1.5.tar.gz", "has_sig": false, "md5_digest": "7267061526bb8a84898ac81f5e5781d7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 985263, "upload_time": "2018-03-30T17:19:50", "url": "https://files.pythonhosted.org/packages/60/c7/7774c635d09a2b6216ecd2a39fb5efdf5dd21cbd025f59dd6f49c9ed4872/connexion-aiohttp-1.5.tar.gz" } ] }