swaggapi 0.6.7

Swagger REST API builder

swaggapi

Swagger OpenAPI 3 wrapper for Python.

This package has the vision of making REST api usage and access - better, faster and easier. For this purpose, you will have to setup few models and "tell" the system what is the structure of each of your requests and responses.

This Python lib will also build automatically swagger.json file which can later on be displayed using Swagger UI.

Features:

• Client and Server rest usage.
• Dynamically generate swagger file.
• Validate input parameters and output responses.

Build your models

Models

First, each of your uri methods ("post", "get", "patch", etc..) has to have a model which represents it. The model class -

class AbstractAPIModel(object):  
  TITLE = None  
  PROPERTIES = []  
  EXAMPLE = None  

Your model should inherit from this object. Examples:

class GenericModel(AbstractAPIModel):  
  """This is an empty model."""
  TITLE = "Generic Object"  
  PROPERTIES = []  
  EXAMPLE = {}

class CatModel(AbstractAPIModel):  
  TITLE = "Cat"  
  PROPERTIES = [  
        NumberField(name="id"),  
        StringField(name="name"),    
        ArrayField(name="friends_ids", items_type=int)
  ]
  EXAMPLE = {
     "id": 0,
     "name": "Garfield",
     "friends_ids": [1, 3]
  }

Class Attributes:

• TITLE (str) - the name of the model, if not set - the class name is taken by default.
• PROPERTIES (list) - list of fields that will represent the model structure.
• EXAMPLE (object) - any kind of json serializeable object.
• __doc__ (str) - the object description.

Response

The response type should also be represented as the model does.

class EmptyResponse(AbstractResponse):  
  """This is an empty response."""
  PROPERTIES = []

Fields

Right now there are 5 types of supported fields: Each field has the following properties:

class Field(object):  
  def __init__(self, name, type, description="", required=False, 
               example=None, location="body", deprecated=False)

Instance Attributes:

• name (str) - the name of the field.
• required (bool) - if the field is required or not (default: False).
• type (str) - string that represents the type of the field.
• description (str) - the field's description.
• example (object) - example of a valid object of the field.
• location (str) - where the field is passed from - possibilities - ["body", "query", "header", "path", "cookie"].
• deprecated (bool) - whether the field is deprecated or not.

If you want to create your own field type, you can expand the following methods -

def default_example(self):  
  """Example in case field didn't specify a unique example."""
  return  

def examples(self, schema_bank, index):
  """In case of complex types field - how should the example be generated."""
  return Example(value=self.example)  

def schemas(self, schema_bank, index):  
  """In case of complex types field - how does the schema should be gennerated."""
  example_ref = get_schema(self, schema_bank, "examples")  
    example = schema_bank[example_ref.type][example_ref.reference]  
    return Schema(title=self.name, type=self.type,  
  description=self.description,  
  example=example.value,  
  deprecated=self.deprecated)

Ready To Go Field Types: ArrayField, StringField, BoolField, NumberField, ModelField.

Build Your Requests

class Request(object):  
    URI = None  
    DEFAULT_MODEL = None  
    DEFAULT_RESPONSES = {}  
    PARAMS_MODELS = {  
       "get": None,  
       "post": None,  
       "delete": None,  
       "put": None,  
       "head": None,  
       "patch": None,  
       "trace": None,  
    }  
    RESPONSES_MODELS = {  
       "get": None,  
       "post": None,  
       "delete": None,  
       "put": None,  
       "head": None,  
       "patch": None,  
       "trace": None,  
    }  
    TAGS = {  
        "get": [],  
        "post": [],  
        "delete": [],  
        "put": [],  
        "head": [],  
        "patch": [],  
        "trace": [],  
    }  

Each request should specify the models of each of the methods. If the request uses a default model you can use the default class attributes for convinence. Tags - are a way to group together responses method.

Django Integration

For this purpose, there is a new defined classes -

class DjangoRequestView(View, Request)
class Response(JsonResponse)
class BadRequest(Exception)
class ServerError(Exception)

• BadRequest - will return httplib.BadRequest status code with the exception details inserted within it.

 raise BadRequest({"details": "Invalid Request"})

• Response - For the validation of the params with the specified model, you should use Response instead of Django's JsonResponse.

return Response({"properties": properties}, status=httplib.OK)

• DjnagoRequestView - each of your views should inherit from this class. this class inherits from the Request object specified above, so everything until now is the same, make sure to fill the required models if their method implemented.

class GetCats(DjangoRequestView):  
  """Get all the cats stored in the system that match the needed query."""  
  URI = "get_cats"  
  DEFAULT_MODEL = CatsDescriptorModel  
  DEFAULT_RESPONSES = {  
        httplib.OK: CatsModel,  
        httplib.BadRequest: NoCatsFoundModel,
  }  
  TAGS = {  
     "post": ["Cats"]  
  }
  # default params are taken because no specific model for this method
  def post(self,  request,  *args,  **kwargs):
      ...
	  return Response({...}, httplib.OK)

• ServerError - thrown when exception occured within the view.

Swagger File Generation

Now when everything is ready we can generate our first swagger file!

Django

Application's urls.py file

from swagapi.build import Swagger
from swagapi.api.openapi.models import Info, License, Tag

requests = [GetCats]  

info = Info(title="Cats OpenAPI",  
            version="0.1.0",  
            description="Cats Swagger for cats management",  
            license=License(name="MIT"))
tags = [Tag(name="Cats",  description="All requests for managing cats")]  
# don't forget to configure the mount_url - all the uri until the current file
swagger = Swagger(info, mount_url="api", requests=requests, tags=tags)  


def swagger_file(request, *args, **kwargs):
    """We dynamically generate the swagger file."""
    swagger.configure_base_url(request)  
    return JsonResponse(swagger.api.json(), status=httplib.OK)  


def index(request, *args, **kwargs):
  """Here we use static deploy for Swagger UI."""
  return render(request, "swagger.html")  


urlpatterns = patterns("",  
  url("^$", index),  
  url("^swagger.json$", swagger_file),  
  *swagger.get_django_urls()  # here all requests uris are automatically built.
)

Client Usage

Simply create a requester -

requester = Requester(host=host,  
  port=port,  
  base_url=self.base_uri,  # Where the api swagger is mounted.
  logger=self.logger)  # optional

And call your request -

request_data = CatsDescriptorModel({   # request parameters
    "cats_ids": [1, 2] 
})  
response = self.requester.request(GetCats,  # rememebr the request class name
  data=request_data,  
  method="post")

# type(response)  == CatsModel if success, NoCatsFoundModel if failed!