Metadata-Version: 1.2
Name: swaggapi
Version: 0.1.0
Summary: Swagger REST API builder
Home-page: UNKNOWN
Author: Elran Shefer
Author-email: elran777@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: # 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 - 
        ```Python
        class AbstractAPIModel(object):  
          TITLE = None  
          PROPERTIES = []  
          EXAMPLE = None  
        ```
        Your model should inherit from this object.
        Examples:
        ```Python
        class EmptyModel(AbstractAPIModel):  
          """This is an empty model."""
          TITLE = "Generic Object"  
          PROPERTIES = []  
          EXAMPLE = {}
        ```
        ```Python
        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.
        ```Python
        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:
        ```Python
        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 - 
        ```Python
        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
        
        ```Python
        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 -  
        ```Python
        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.
        ```Python
         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.
        ```Python
        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.
        ```Python
        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
        ```Python 
        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 - 
        ```Python
        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 -
        ```Python
        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!
        ```
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2.7
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: ~=2.7.0
