Metadata-Version: 1.1
Name: flask-swagger
Version: 0.2.14
Summary: Extract swagger specs from your flask project
Home-page: https://github.com/gangverk/flask-swagger
Author: Atli Thorbjornsson
Author-email: UNKNOWN
License: MIT
Description: flask-swagger
        =============
        
        A Swagger 2.0 spec extractor for Flask
        
        Install:
        
        ::
        
            pip install flask-swagger
        
        Flask-swagger provides a method (swagger) that inspects the Flask app
        for endpoints that contain YAML docstrings with Swagger 2.0
        `Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
        objects.
        
        ::
        
            class UserAPI(MethodView):
        
                def post(self):
                    """
                    Create a new user
                    ---
                    tags:
                      - users
                    definitions:
                      - schema:
                          id: Group
                          properties:
                            name:
                             type: string
                             description: the group's name
                    parameters:
                      - in: body
                        name: body
                        schema:
                          id: User
                          required:
                            - email
                            - name
                          properties:
                            email:
                              type: string
                              description: email for user
                            name:
                              type: string
                              description: name for user
                            address:
                              description: address for user
                              schema:
                                id: Address
                                properties:
                                  street:
                                    type: string
                                  state:
                                    type: string
                                  country:
                                    type: string
                                  postalcode:
                                    type: string
                            groups:
                              type: array
                              description: list of groups
                              items:
                                $ref: "#/definitions/Group"
                    responses:
                      201:
                        description: User created
                    """
                    return {}
        
        Flask-swagger supports docstrings in methods of MethodView classes and
        regular Flask view functions.
        
        Following YAML conventions, flask-swagger searches for ``---``,
        everything preceding is provided as ``summary`` (first line) and
        ``description`` (following lines) for the endpoint while everything
        after is parsed as a swagger
        `Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
        object.
        
        In order to support inline definition of
        `Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
        objects in
        `Parameter <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject>`__
        and
        `Response <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject>`__
        objects, flask-swagger veers a little off from the standard. We require
        an ``id`` field for the inline Schema which is then used to correctly
        place the
        `Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
        object in the
        `Definitions <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject>`__
        object.
        
        `Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
        objects can be defined in a definitions section within the docstrings (see group object above) or within responses or parameters (see user object above). We alo support schema objects nested within the properties of other
        `Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
        objects. An example is shown above with the address property of User.
        
        To expose your Swagger specification to the world you provide a Flask
        route that does something along these lines
        
        ::
        
            from flask import Flask, jsonify
            from flask_swagger import swagger
        
            app = Flask(__name__)
        
            @app.route("/spec")
            def spec():
                return jsonify(swagger(app))
        
        Note that the Swagger specification returned by ``swagger(app)`` is as
        minimal as it can be. It's your job to override and add to the
        specification as you see fit.
        
        ::
        
            @app.route("/spec")
            def spec():
                swag = swagger(app)
                swag['info']['version'] = "1.0"
                swag['info']['title'] = "My API"
                return jsonify(swag)
        
        `Swagger-UI <https://github.com/swagger-api/swagger-ui>`__
        
        Swagger-UI is the reason we embarked on this mission to begin with,
        flask-swagger does not however include Swagger-UI. Simply follow the
        awesome documentation over at https://github.com/swagger-api/swagger-ui
        and point your
        `swaggerUi.url <https://github.com/swagger-api/swagger-ui#swaggerui>`__
        to your new flask-swagger endpoint and enjoy.
        
        Acknowledgments
        
        Flask-swagger builds on ideas and code from
        `flask-sillywalk <https://github.com/hobbeswalsh/flask-sillywalk>`__ and
        `flask-restful-swagger <https://github.com/rantav/flask-restful-swagger>`__
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Software Development :: Libraries :: Python Modules
