Connexion - API first applications with OpenAPI/Swagger and Flask
Project description
Connexion
Connexion is a framework on top of Flask to automagically handle your REST API requests based on OpenAPI 2.0 Specification (formerly known as Swagger Spec) files in YAML.
How to use
Put your API YAML inside a folder in the root path of your application (e.g swagger/) and then do
import connexion
app = connexion.App(__name__, specification_dir='swagger/')
app.add_api('my_api.yaml')
app.run(port=8080)See the Connexion Pet Store Example Application for details.
Parameterization
Connexion uses Jinja2 to allow the parameterization of specifications.
The specification arguments can be defined globally for the application or for each specific API:
app = connexion.App(__name__, specification_dir='swagger/', arguments={'global': 'global_value'})
app.add_api('my_api.yaml', arguments={'api_local': 'local_value'})
app.run(port=8080)If a value is provided both globally and on the API then the API value will take precedence.
Endpoint Routing
Connexion uses the operationId from each Operation Object to identify which function should handle each URL.
For example:
paths:
/hello_world:
post:
operationId: myapp.api.hello_worldIf you provided this path in your specification POST requests to http://MYHOST/hello_world would be handled by the function hello_world in myapp.api. Optionally you can include x-swagger-router-controller in your operation definition, making operationId relative:
paths:
/hello_world:
post:
x-swagger-router-controller: myapp.api
operationId: hello_worldTo customize this behavior, Connexion can use alternative Resolvers, for example RestyResolver. The RestyResolver will compose an operationId based on the path and HTTP method of the endpoints in your specification:
from connexion.resolver import RestyResolver
app = connexion.App(__name__)
app.add_api('swagger.yaml', resolver=RestyResolver('api'))paths:
/:
get:
# Implied operationId: api.get
/foo:
get:
# Implied operationId: api.foo.search
post:
# Implied operationId: api.foo.post
'/foo/{id}':
get:
# Implied operationId: api.foo.get
put:
# Implied operationId: api.foo.post
copy:
# Implied operationId: api.foo.copy
delete:
# Implied operationId: api.foo.deleteRestyResolver will give precedence to any operationId encountered in the specification. It will also respect x-router-controller. You may import and extend connexion.resolver.Resolver to implement your own operationId (and function) resolution algorithm.
Additionally you can also define a basePath on the top level of the API specification, which is useful for versioned APIs. If you wanted to serve the previous endpoint from http://MYHOST/1.0/hello_world you could do:
basePath: /1.0
paths:
/hello_world:
post:
operationId: myapp.api.hello_worldOther alternative if you don’t want to include the base path in your specification is provide the base path when adding the API to your application:
app.add_api('my_api.yaml', base_path='/1.0')Response Serialization
If the specification defines that a endpoint returns JSON, Connexion will automatically serialize the return value for you and set the right content type in the HTTP header.
Swagger JSON
Connexion makes the OpenAPI/Swagger specification in JSON format available from swagger.json in the base path of the API.
Swagger UI
The Swagger UI for an API is available, by default, in {base_path}/ui/ where base_path is the base path of the API.
You can disable the Swagger UI either at application level:
app = connexion.App(__name__, specification_dir='swagger/', swagger_ui=False)
app.add_api('my_api.yaml')You can also disable it at API level:
app = connexion.App(__name__, specification_dir='swagger/')
app.add_api('my_api.yaml', swagger_ui=False)Server Backend
By default Connexion uses the default Flask server but you can also use Tornado as the HTTP server, to do so set server to tornado:
import connexion
app = connexion.App(__name__, specification_dir='swagger/')
app.run(server='tornado', port=8080)You can use the Flask WSGI app with any WSGI container, e.g. using Flask with uWSGI:
app = connexion.App(specification_dir='swagger/')
application = app.app # expose global WSGI application object$ sudo pip3 install uwsgi
$ uwsgi --http :8080 -w app -p 16 # use 16 worker processesYou can run uWSGI with a large number of worker processes to get high concurrency.
See the uWSGI documentation for more information.
Releasing Connexion
Build and upload new version to PyPI:
$ ./release.sh <NEW-VERSION>License
Copyright 2015 Zalando SE
Licensed 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
Unless 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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file connexion-1.0.57.tar.gz.
File metadata
- Download URL: connexion-1.0.57.tar.gz
- Upload date:
- Size: 835.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
392a06de9333580f9f9705136ab58feebc97eef15234012746763ce136eb0468
|
|
| MD5 |
5c6b87cb1361e62c9c3794bf57efa90b
|
|
| BLAKE2b-256 |
80cccc513fe8e1b08eed55259f0b83ed06732ce9f0a308f8667421e8bb46e9b5
|
File details
Details for the file connexion-1.0.57-py3-none-any.whl.
File metadata
- Download URL: connexion-1.0.57-py3-none-any.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
33a1244df01f565f3ff91f12aeaf3cfcdc0261515b57e5e46f035771001310c7
|
|
| MD5 |
80549b46a9c4d9de9c6b126e63eae566
|
|
| BLAKE2b-256 |
34c9262fb317b3ae9ad1bd2d6aefb7ef7d57aa86a1670a244aea2b68ce696c3f
|
