Skip to main content

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/

travisci

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!

Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
Flask-Sillywalk-2.1.zip (16.3 kB) Copy SHA256 hash SHA256 Source None Mar 4, 2015

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page