Metadata-Version: 1.1
Name: swaggery
Version: 1.0.0a1
Summary: A Python3 framework to create self-documenting swagger APIs
Home-page: https://github.com/quasipedia/swaggery
Author: Mac Ryan
Author-email: quasipedia@gmail.com
License: AGPLv3+
Description: Swaggery
        ========
        
        A python3 framework to code self-documenting RESTful API's according to the
        [swagger](https://swagger.io) specifications.
        
        The project currently support swagger specifications 1.2, migration to version
        2.0 is underway.
        
        Serving the application via uWSGI is a **temporary requirement** as this is
        presently the only WSGI server to provide support for the `yeld from` syntax.
        
        As soon as [native support for `asyncio` will become stable]
        (http://uwsgi-docs.readthedocs.org/en/latest/asyncio.html), Swaggery will be
        refactored to use that (hopefully universal, and thus supported by other WSGI
        servers) mechanism.
        
        
        
        Design principles
        -----------------
        
          - **Lightweight** - Swaggery is not built on top of web application
            frameworks designed to serve websites.  It is built ground-up for serving
            swagger APIs.  The only core dependency is [werkzeug]
            (http://werkzeug.pocoo.org/).
          - **Consistent** - Swaggery has born from the observation that in large
            corporate environments (but in poorly managed small projects too!) APIs
            tend to become inconsistent over time: as various endpoints are implemented
            by various people, the naming conventions, data containers and/or types
            multiply, making the API more difficult to use and buggy than it ought to
            be.  Swaggery tries to mitigate this phenomenon by using classes with a
            well defined interface that self-document themselves in a consistent
            manner.
          - **Concurrent** - Swaggery has been designed from day #1 to be concurrent.
            Concurrency is not an afterthought achieved with a hack, it has been the
            first stone to be laid down at the beginning of the project.
          - **Testable** - The uniform interface of Swaggery endpoints, that have no
            side effects makes unit-testing very easy to do.
          - **Modern** - The upside of Swaggery being a new project that doesn't build
            onto large, multi-purpose frameworks (read: flask, django, etc...) is that
            it was possible to use modern python to build it.  In particular,
            Swaggery heavily relies on the `yeld from syntax` introduced in Python 3.3
            and function annotations, introduced in Python 3.0.  As soon as this will
            be supported by at least one of the major WSGI servers, Swaggery will
            be modified (read: simplified!) to run on the `asyncio` loop (introduced
            in python 3.4).
        
        
        Quick Start
        -----------
        
        After having installed the dependencies in the virtual environment, you will
        have to create your own `swaggery.ini` file.
        
        A template can be found at `/templates/swaggery.ini`.  After you have done,
        just type:
        
            uwsgi swaggery.ini
        
        
        
        Creating your own API
        ---------------------
        
        Swaggery APIs are created by subclassing 3 main "abstract" classes:
        
        ### Model ###
        
        Models define the data strcutures used by the API.  Since Swaggery is based on
        JSON-schema, the native data types are readily available in the `models.py`
        module (where the abstract `Model` class also lives).
        
        Models are referenced in the Endpoint method signatures, so they need to be
        declared (or imported) before defining any Endpoint, as they will be avaluated
        at import time.
        
        Model classes have a single class attribute called "schema" which must conform
        to JSON schema syntax (see: [here](http://json-schema.org/) and
        [here](https://github.com/wordnik/swagger-core/wiki/datatypes)).
        
        
        ### Api ###
        
        APIs are just lightweight containers grouping related resources.  Since they do
        not perform any particular type of operation, their declaration is
        straighforward:
        
            class ZombieManipulation(Api):
        
                '''A beautiful API allowing to manipulate zombies.'''
        
                version = '1.0.0'
                path = 'zombies'
        
        
        ### Resources ###
        
        Resources are "entities" that can be manipulated atomically.  They are mapped
        to a single, unique URL/endpoint.  And the manipulation happens via HTTP verbs.
        The URL can be either _static_ (`/zombies`) or _dynamic_ (`/zombies/{id}`),
        were the `{id}` part means the ID value is a variable supplied by the client.
        
        Operations on the entities are performed by calling the endpoint with the
        appropriate HTTP method/verb.  For example you might issue a `GET` on
        `/zombies/666` and the server might return the strength, stamina, and max
        velocity of the zombie #666.  Alternatively you might `POST` to the same URL,
        adding either a form or a body to the request, with the strength, stamina and
        max velocity of a zombie to be newly created.
        
        Back to Swaggery...
        
        A Resoruce is implemented by subclassing the `Resource` class.  Operations are
        implented as class methods, decorated with the `operations` function.
        
        Class methods need to be fully annotated, and have a docstring, to make
        possible for Swaggery to instrospect them correctly.  For example:
        
            class AddVectors(Resource):
        
                '''Single vector operations.'''
        
                api = Calculator
                subpath = 'vector'
        
                @operations('POST')
                def length(
                        cls, request,
                        vector: (Ptypes.body,
                                 Vector('The vector to analyse.'))) -> [
                        (200, 'Ok', Float),
                        (400, 'Wrong vector format')]:
                    '''Return the modulo of a vector.'''
                    <your-code-here>
        
        Will be rendered as the following swagger description:
        
            {
                "description": "Single vector operations.", 
                "operations": [
                    {
                        "method": "POST", 
                        "nickname": "length", 
                        "notes": "", 
                        "parameters": [
                            {
                                "type": "Vector",
                                "description": "The vector to analyse.", 
                                "name": "vector", 
                                "paramType": "body", 
                                "required": true
                            }
                        ], 
                        "responseMessages": [
                            {
                                "code": 200, 
                                "message": "Ok", 
                                "responseModel": "float"
                            }, 
                            {
                                "code": 400, 
                                "message": "Wrong vector format", 
                                "responseModel": "void"
                            }
                        ], 
                        "summary": "Return the modulo of a vector.", 
                        "type": "float"
                    }
                ], 
                "path": "/calc/vector"
            }
        
        See the full example int the `examples/calculator` folder.
        
        
        
        Stuff that needs to be documented
        ---------------------------------
        
          - Use sphinx
          - Return mechanism (Fail vs. return)
          - How testing is easy
          - Only one callback for each HTTP (REST)
          - Request is passed as a courtesy, but shouldn't be used for business logic
          - Ptypes
          - Streaming answers
          - swaggery.ini file
          - testlib
          - Subpath
          - Checker
        
        
        
        FAQ
        ---
        
        
        ### Where is the Python 2.X compatible version? ###
        
        Support for python 2.x series **cannot** be provided as the library heavily
        relies on function annotation, which has been introduced in python 3.0 as well
        as from the `yield from` syntax introduced in v 3.3.
Keywords: swagger API documentation asyncronous framework uWSGI WSGI
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Documentation
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
