API Documentation

A Swagger documentation of our REST endpoints is available using

http://backend-deployment:5000/static/swagger/index.html

given default host and port settings.

A deployed version of our documentation is available here.

How to document a new endpoint?

We use flask-restful-swagger-2 that adds swagger support to our Flask app according to the swagger 2.0 specification.

Therefore it is really easy to document the newly created endpoint right in the code as you can see in the following example:

    class EdgeResource(Resource):
    @swagger.doc({
        'description': 'Returns a single edge',
        'parameters': [
            {
                'name': 'edge_id',
                'description': 'Edge identifier',
                'in': 'path',
                'type': 'integer',
                'required': True
            }
        ],
        'responses': get_default_response(EdgeSchema.get_swagger()),
        'tags': ['Edge']
    })
    def get(self, edge_id):
        edge = Edge.query.get_or_404(edge_id)

        return marshal(EdgeSchema, edge)

The responses are automatically created by get_default_response (imported from src.master.helpers.swagger)