Swagger generated server

Overview

This server was generated by the swagger-codegen project. By using the OpenAPI-Spec from a remote server, you can easily generate a server stub. This is an example of building a swagger-enabled Flask server.

This example uses the Connexion library on top of Flask.

Requirements

Python 3.5.2+

Usage

To run the server, please execute the following from the root directory:

pip3 install -r requirements.txt
python3 -m swagger_server

and open your browser to here:

http://localhost:8080/api/ui/

Your Swagger definition lives here:

http://localhost:8080/api/swagger.json

To launch the integration tests, use tox:

sudo pip install tox
tox

Running with Docker

To run the server on a Docker container, please execute the following from the root directory:

# building the image
docker build -t swagger_server .

# starting up a container
docker run -p 8080:8080 swagger_server

Development

Building the Rest API from Swagger

The UN Treaties REST API has been automatically mostly generated from this configuration file: ./swagger_server/swagger/swagger.yaml. The models (under ./swagger_server/models/) and the controllers (under ./swagger_server/controllers) are only provided as empty sets of class and functions to actually build the responses to API requests.

You may already 3 easy ways to rebuilt the "empty" Swagger API:

• Install the java-based Swagger Code Generator locally

  1. Download the swagger-codegen-cli: https://github.com/swagger-api/swagger-codegen/#prerequisites

  2. Generate the rest-api:

     $ java -jar swagger-codegen-cli.jar generate -l python-flask -i swagger.yaml -c swagger_config.json -o swagger_build

     Unfortunately, there seems to be some bug in swagger-codegen-cli (or config setting we have not figured out) that causes some code to be put into un_treaties.rest_api instead of un_treaties/rest_api. Also, the command generates some files like setup.py that we don't want in our project. Because of this we save everything in a temporary folder, swagger_build

  3. Move files from swagger_build into un_treaties. Essentially all files inside of swagger_build/un_treaties/rest_api and swagger_build/un_treaties.rest_api should be moved to un_treaties/rest_api. The files in swagger_build outside these directories should not be moved.

  4. Delete the temporary directory swagger_build.

• Use the online Swagger editor and generate the server code from there.

• Run a local Docker version of the Swagger Editor if you are afraid of loosing your internet connection. docker run -d -p 80:8080 swaggerapi/swagger-editor and open it http://localhost:80

Running the API with Docker

We use Docker to deploy the API on Heroku.

• Build th Docker image: docker build -t un-treaties-api:latest .
• Run the image locally: docker run -p 5000:5000 un-treaties-api

You can check that the API runs on your local machine at this URL:

Deploy your dockerized app on Heroku

• isntall Heroku: sudo snap install heroku --classic
• Login to your Heroku account after creating one here: heroku login
• Add Heroku as a git repository to your app: heroku create un-treaties

You can check

$ git remote -v
heroku	https://git.heroku.com/un-treaties.git (fetch)
heroku	https://git.heroku.com/un-treaties.git (push)
origin	git@github.com:DataForGood-Norway/un_treaties.git (fetch)
origin	git@github.com:DataForGood-Norway/un_treaties.git (push)

• Set the stack of your app to container: heroku stack:set container
• then simply push your app the Heroku container registry: git push heroku master
• run the app on Heroku: heroku ps:scale web=1
• open you are from the terminal: heroku open

In case you need to debug your deployment to Heroku, this simple example has been helpful: https://deparkes.co.uk/2018/05/28/deploy-docker-to-heroku/