hjacobs / connexion-example

Example REST service using Connexion Swagger-first Python library: includes schema validation and OAuth 2

Connexion Example REST Service

This example application implements a very basic "pet shop" REST service using the Connexion Python library.

Connexion is a framework on top of Flask to automagically handle your REST API requests based on Swagger 2.0 Specification files in YAML.

👉 Please also have a look at the Connexion Example with Redis database and Kubernetes deployment manifests.

Features

This example application shows various features supported by the Connexion library:

• mapping of REST operations to Python functions (using the operationId in swagger.yaml)
  • maps path, query and body parameters to keyword arguments
• bundled Swagger UI (served on /ui/ path)
• automatic JSON serialization for application/json content type
• schema validation for the HTTP request body and query parameters:
  • required object properties
  • primitive JSON types (string, integers, etc)
  • date/time values
  • string lengths
  • minimum/maximum values
  • regular expression patterns
• gevent WSGI server
• OAuth2 protection

Files

The example application only needs very few files:

• swagger.yaml: the pet shop REST API Swagger definition
• app.py: implementation of the pet shop operations with in-memory storage
• Pipfile: list of required Python libraries (used by Pipenv)
• Dockerfile: to build the example as a runnable Docker image
• test.sh: shell script to execute example HTTP requests against the pet shop API

Running Locally

You can run the Python application directly on your local operating system (this requires Python 3 and Pipenv):

$ pipenv install --dev && pipenv shell
$ ./app.py # start the HTTP server
$ xdg-open http://localhost:8080/ui/
$ ./test.sh # do some test HTTP requests

Running with Docker

You can build the example application as a Docker image and run it:

$ docker build -t connexion-example .
$ docker run -d -p 8080:8080 connexion-example
$ ./test.sh # do some test HTTP requests

Using OAuth2 Security

To enable OAuth2 security (token verification), you need to pass the URL to the "tokeninfo" endpoint:

$ docker run -d -p 8080:8080 -e HTTP_TOKENINFO_URL=https://auth.example.org/tokeninfo connexion-example

Using Connexion with a WSGI container

You can use the Flask WSGI app with any WSGI container, e.g. using Flask with uWSGI:

$ sudo pip3 install uwsgi
$ uwsgi --http :8080 -w app

You can run uwsgi with a large number of worker processes to get high concurrency. This obviously makes no sense for the in-memory pet store example (every worker would have its own pet store dictionary):

$ uwsgi --http :8080 -w app -p 16  # use 16 worker processes

See the uWSGI documentation for more information.

connexion-example's Issues

support for Python 2.7.x?

How to do I enable cross-domain requests?

Thank you very much!

I had to spend much time yesterday and today trying to get several software packages up and running. Mostly without full success. Frustrating. But I tried this one and it DOES work as promised right out of the box, with Docker. Hooray! You're saving my day! Your work is totally in line with what I had unausgegoren (totally unready) in my head. I'm so happy the last meetup had pointed me to this direction. Happy Christmas!
https://www.meetup.com/de-DE/monster-tech-tales-software-engineering-user-group-muenster/events/235728759/

Trying to understand the oauth2 scope and how security works

Hi there,

I'm soon publishing a blog post about how to use this library, I'm still missing a point though, how does the security work?
I have my project in pycharm and before starting your example I set HTTP_TOKENINFO_URL=https://auth.example.org/tokeninfo as global variable but I don't know what I am missing. I absolutely don't know what I am doing and I'd be glad to get some help here..
Thanks a lot!

Alternatively, how would I set up a simple "password"?

I am trying to use your framework to test api with my specifications. but getting the error.

I want to use your framework for testing my API. I have swagger specification file. I did some changes in your code but unable to test the API. Can you suggest me what changes I should perform to make the testing run. My specification file is shown below.

swagger: "2.0"

################################################################################

API Information

################################################################################
info:
version: "1.0.0"
title: API Documentation
description: "This documentation contain specifications of API which were used for getting the information from open data source"

produces:

• application/json

################################################################################

Security

################################################################################

################################################################################

Paths

################################################################################
paths:
/opendata/v1/{index}:
get:
tags: [verification]
description: Verify the person information
parameters:
- name: index
in: path
description: specific data index
required: true
type: string
- name: name
in: query
description: name of a person
required: false
type: string
- name: company name
in: query
description: name of a company
required: false
type: string

  responses:
    '200':
      $ref: '#/responses/200'

################################################################################

Definitions

################################################################################

responses:
'200':
description: Success
schema:
type: object
properties:
verification:
type: boolean

Thanks

Thanks

Nice example would be nice to have a mongoDb as well.

Path parameters converted to integers

Fairly new to Python and Connexion.

I have a definition:

  - in: path
    name: orgid
    schema:
      type: string
    required: true
    description: ID of the organisation

and the function that provides information on this URL:
def getOrgById (schemeid,orgid):

Some organisation ids are all numeric. I can convert them to a string, and that's fine but if the organisation id starts with a '0', it gets lopped off.
/organisations/1234
is OK but
/organisations/0563
breaks - because the value of orgid in the function is '563' .

How can I ensure that the parameter is passed to the function as a string and not an integer? Specifying it as a string in the YAML ought to be enough, I'd have thought.

Add example Dockerfile with Alpine Linux base image and gevent

Running Python 3 with Alpine Linux and gevent is actually quite easy and results in a notably smaller Docker image size (~75 MB total).

Existing example: https://github.com/hjacobs/kube-ops-view/blob/master/Dockerfile

Default values for animal fields

Hello, thank for good example.
I am try set default values for not required fields, I remove
pet['created'] = datetime.datetime.utcnow()
from code and add
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -115,9 +115,9 @@ definitions:
format: date-time
description: Creation time
example: "2015-07-07T15:49:51.230+02:00"
{+default: "2015-07-07T15:49:51.230+02:00"+}
but it does not work, I read this and try different variants, but nothing work.
It is swagger/connexion bug or it is bug in my understanding?