Code Monkey home page Code Monkey logo

flask-sillywalk's Introduction

flask-sillywalk

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!

flask-sillywalk's People

Contributors

delijati avatar hobbeswalsh avatar mplewis avatar oalifdal avatar rantav avatar remear avatar tarnacious avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.