README

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>`__