Metadata-Version: 1.1
Name: cornice_swagger
Version: 0.2.1
Summary: Generate swagger from a Cornice application
Home-page: https://github.com/Cornices/cornice.ext.swagger
Author: Josip Delic
Author-email: delijati@gmx.net
License: Apache License (2.0)
Description: cornice_swagger
        ===============
        
        *Cornice extension to generate Swagger*
        
        Git Repository and issue tracker: https://github.com/Cornices/cornice.ext.swagger
        
        .. |travisci| image::  https://travis-ci.org/Cornices/cornice.ext.swagger.png
        .. _travisci: https://travis-ci.org/Cornices/cornice.ext.swagger
        
        .. image:: https://coveralls.io/repos/Cornices/cornice.ext.swagger/badge.png
            :target: https://coveralls.io/r/Cornices/cornice.ext.swagger
        
        |travisci|_
        
        To create a full swagger spec, this module will maximize extracting
        documentation data from functional code, while allowing users to
        directly specify parts of the Swagger Spec. This documentation serves as
        a "how-to". Readers are encouraged to look at the source for more
        detailed documentation if needed.
        
        This module creates a `Swagger 2.0 compliant spec`_.
        
        Throughout this documentation, ``code-styled text`` indicates a sort of
        "proper noun" matching the official names used in related documentation
        (Swagger Spec, Cornice, Pyramid, Colander).
        
        **Outline**
        
        1. Docstrings
        2. Swagger Module
        3. Converters
        
           1. Colander for input parameters
        
        4. Scaffold
        
        Description Docstrings
        ======================
        
        -  ``cornice.resource.resource``-decorated classes in your view file should
           have docstrings (triple-quoted strings immediately after your class
           declaration)
        
           -  This docstring becomes the description for the respective endpoint
              group.
           -  Each endpoint group is a collection of Swagger Paths which start
              with the same URL base (the text between the first two ``/``
              characters in your URL after the true URL base).
        
        -  ``cornice.resource.view``-decorated methods with your decorated Cornice
           Resource classes should have docstrings to document the individual
           HTTP method descriptions
        
        *Note* The Swagger UI groups together endpoints which share the same
        ``tag``. The swagger module auto-tags all endpoints based on their path
        beginning. Technically, a Swagger Spec stores a ``basePath`` in the
        `root document object`_. However, as a well-formed REST URI begins with
        a RESTful object with which to be interacted, this object (between the
        first slashes) will be used to tag similar paths into a group.
        
        *Warning* If you implement multiple ``@resource``-decorated classes
        beginning with the same first URL segment in the ``path`` argument, it
        may become ambiguous which docstring will be displayed in Swagger UI.
        Only put a docstring on one such class to remove ambiguity.
        
        Swagger Module
        ==============
        
        ``swagger.py`` uses
        ``generate_swagger_spec(services, title, version, **kwargs)`` to make
        the actual Swagger Spec JSON. The arguments are:
        
        .. _Swagger 2.0 compliant spec: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
        .. _root document object: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#fixed-fields
        
        1. ``services`` - a list of Pyramid Services. Note that Cornice
           Resources are really Services under the hood.
        2. ``title`` and ``version`` are both required Swagger Spec details for
           the `Info Object`_.
        3. ``kwargs`` can be made of anything else which would go into the base
           `Swagger Object`_.
        
        *Note* If you want to add to the ``Info Object``, simply pass in as an
        ``info`` argument with the additional details. The ``Info Object``
        populated by the ``title`` and ``version`` args provided earlier will
        simply be updated.
        
        An example of a Pyramid Service which itself scans other Cornice
        Resources and Services to generate a ``swagger.json`` Spec:
        
        .. code:: python
        
           from pyramid.view import view_config
           from cornice import service
           from swagger import generate_swagger_spec
        
        
           @view_config(route_name="swagger", renderer="templates/index.pt")
           def swagger(request):
               return {"request": request}
        
        
           @view_config(route_name="swagger_json", renderer="json")
           def swagger_json(request):
               info = {"title": "Joes API", "version": "0.1", "contact": {
                       "name": "Joe Smith",
                       "email": "joe.cool@swagger.com"}
                       }
               base_path = "/"
               services = get_services()
               spec = generate_swagger_spec(services, info["title"],
                                            info["version"], info=info,
                                            base_path=base_path, head=False)
               return spec
        
        Swagger-UI integration
        ----------------------
        
        To serve the swagger-ui we create a ``index.html`` and download the needed js
        files with ``bower``.
        
        .. code:: html
        
           <!DOCTYPE html>
           <html>
        
           <head>
               <!-- swagger -->
               <link href="${request.static_url('foo:static/bower_components/swagger-ui/dist/css/typography.css')}"
               type='text/css' rel="stylesheet" />
               <link href="${request.static_url('foo:static/bower_components/swagger-ui/dist/css/reset.css')}"
               type='text/css' rel="stylesheet" />
               <link href="${request.static_url('foo:static/bower_components/swagger-ui/dist/css/screen.css')}"
               type='text/css' rel="stylesheet" />
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/object-assign-pollyfill.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/jquery-1.8.0.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/jquery.slideto.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/jquery.wiggle.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/jquery.ba-bbq.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/handlebars-2.0.0.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/lodash.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/backbone-min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/dist/swagger-ui.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/highlight.9.1.0.pack.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/highlight.9.1.0.pack_extended.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/jsoneditor.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/js-yaml.min.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/marked.js')}"></script>
               <script src="${request.static_url('foo:static/bower_components/swagger-ui/lib/swagger-oauth.js')}"></script>
           </head>
        
           <body>
               <div class="swagger-section container">
                   <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
               </div>
               <script type="text/javascript">
                   $(function()
                   {
                       var swaggerUi = new SwaggerUi(
                       {
                           url: "${request.route_url('swagger_json')}",
                           dom_id: "swagger-ui-container",
                           validatorUrl: null,
                           docExpansion: "list"
                       });
                       swaggerUi.load();
                   });
               </script>
           </body>
        
           </html>
        
        Converters
        ----------
        
        Ideally, we'd maximaize how much documentation comes from functional code. As
        we're already using Cornice, we can leverage its operators internally to
        ``generate_swagger_spec()``. This only gets us so far, and currently only
        leverages the ``@resource`` decorator as it identifies services and provides
        some path info from which to gleen ``path`` parameters and a description. For
        example, this code...
        
        .. code:: python
        
           class Body(MappingSchema):
               # foo and bar are required, baz is optional
               foo = SchemaNode(String())
               ipsum = SchemaNode(Integer(), missing=1, validator=Range(0, 3))
               integers = Integers(missing=())
        
        
           class Query(MappingSchema):
               yeah = SchemaNode(String())
               mau = SchemaNode(String())
        
        
           class RequestSchema(MappingSchema):
               body = Body(description="Defines a cornice body schema")
               querystring = Query()
        
           @resource(collection_path='/tokens', path='/tokens/{authId}',
                     description='quick token description')
           class Token(object):
               """Authenticate by POSTing here"""
               def __init__(self, request):
                   self.request = request
        
               @view(validators=(colander_validator, ), schema=RequestSchema())
               def collection_post(self):
                   """Get authKey here and use as X-Identity-Token for future calls"""
                   ...
               def delete(self):
                   """Log out of system by deleting a token from your previous authId"""
                   ...
        
        Colander
        ~~~~~~~~
        
        Since Cornice recommends Colander for validation, there are some handy
        converters to convert Colander ``Schemas Nodes`` to Swagger ``Parameter
        Objects``.
        
        If you have defined Cornice ``Schema`` objects (comprised of ``Schema Nodes``),
        you can pass it to ``schema_to_parameters`` which then converts the ``Schema``
        to a list of ``Swagger Parameters``. Since ``Schema Nodes`` take in a Colander
        type as an argument (``Tuple``, ``Boolean``, etc) the Swagger ``Parameter
        Object`` "type" can be derived. This function is used by
        ``generate_swagger_spec`` to scan for Colander Schmas being decorated onto an
        ``Operation`` with the Cornice ``@view(schema=MyCoolSchema`` decorator, and the
        create ``Parameter Objects``
        
        Scaffold
        --------
        
        To get easier started there is a scaffold with can be used.
        
        ::
        
           $ cookiecutter https://github.com/delijati/cookiecutter-cornice_swagger.git
           $ cd demo
           $ pip install -e .
           $ cd demo/static
           $ bower install
        
        Contributors
        ============
        
        - Jason Haury
        
        - Josip Delic
        
        
        CHANGES
        =======
        
        0.2.1 (2016-12-10)
        ------------------
        
        - Check if schema is not instantiated.
        
        - Add support for query parameter description. [ridha]
        
        
        0.2 (2016-11-08)
        ----------------
        
        - Pypi release.
        
        - Point scaffold doc to right url.
        
        
        0.1 (2016-11-05)
        ----------------
        
        - First release for new cornice 2.0 
        
Keywords: web services
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: Apache Software License
