Metadata-Version: 1.0
Name: flask-swagger
Version: 0.2.0
Summary: Extract swagger specs from your flast-restful 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
                    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
                    responses:
                      201:
                        description: User created
                    """
                    return {}
        
        flask-swagger supports docstrings in 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
        `Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
        and
        `Response <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject>`__
        items, 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.
        
        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
