Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (testpypi.python.org).
Help us improve Python packaging - Donate today!

So you want to implement an auto-documenting API?

Project Description

A Flask extension that implements Swagger support (http://swagger.wordnik.com/)

What’s Swagger?

Swagger is a spec to help you document your APIs. It’s flexible and produces beautiful API documentation that can then be used to build API-explorer-type sites, much like the one at http://developer.wordnik.com/docs – To read more about the Swagger spec, head over to https://github.com/wordnik/swagger-core/wiki or http://swagger.wordnik.com

Git Repository and issue tracker: https://github.com/hobbeswalsh/flask-sillywalk Documentation: http://flask-sillywalk.readthedocs.org/en/latest/

Why do I want it?

  • You want your API to be easy to read.
  • You want other people to be able to use your API easily.
  • You’d like to build a really cool API explorer.
  • It’s Friday night and your friend just ditched on milkshakes.

How do I get it?

From your favorit shell:

$ pip install flask-sillywalk

How do I use it?

I’m glad you asked. In order to use this code, you need to first instantiate a SwaggerApiRegistry, which will keep track of all your API endpoints and documentation.

Usage:

from flask import Flask
from flask.ext.sillywalk import SwaggerApiRegistry, ApiParameter, ApiErrorResponse

app = Flask("my_api")
registry = SwaggerApiRegistry(
  app,
  baseurl="http://localhost:5000/api/v1",
  api_version="1.0",
  api_descriptions={"cheese": "Operations with cheese."})
register = registry.register
registerModel = registry.registerModel

Then, instead of using the “@app.route” decorator that you’re used to using with Flask, you use the “register” decorator you defined above (or “registerModel” if you’re registering a class that describes a possible API return value).

Now that we’ve got an API registry, we can register some functions. The @register decorator, when just given a path (like @app.route), will register a GET mthod with no possible parameters. In order to document a method with parameters, we can feed the @register function some parameters.

Usage:

@register("/api/v1/cheese/random")
def get_random_cheese():
  """Fetch a random Cheese from the database.
  Throws OutOfCheeseException if this is not a cheese shop."""
  return htmlify(db.cheeses.random())

@register("/api/v1/cheese/<cheeseName>",
  parameters=[
    ApiParameter(
        name="cheeseName",
        description="The name of the cheese to fetch",
        required=True,
        dataType="str",
        paramType="path",
        allowMultiple=False)
  ],
  responseMessages=[
    ApiErrorResponse(400, "Sorry, we're fresh out of that cheese.")
  ])
def get_cheese(cheeseName):
  """Gets a single cheese from the database."""
  return htmlify(db.cheeses.fetch(name=cheeseName))

Now, if you navigate to http://localhost:5000/api/v1/resources.json you should see the automatic API documentation. See documentation for all the cheese endpoints at http://localhost:5000/api/v1/cheese.json

What’s left to do?

Well, lots, actually. This release:

  • Doesn’t support XML (but do we really want to?)
  • Doesn’t support the full swagger spec (e.g. “type” in data models
  • Lots more. Let me know!
Release History

Release History

This version
History Node

2.1

History Node

2.0

History Node

1.0

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
Flask-Sillywalk-2.1.zip (16.3 kB) Copy SHA256 Checksum SHA256 Source Mar 4, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting