Flask-Sillywalk 2.1

什么是招摇？

Swagger 是帮助您记录 API 的规范。它很灵活，可以生成漂亮的 API 文档，然后可以用来构建 API 浏览器类型的站点，就像 http://developer.wordnik.com/docs上的站点一样——要了解更多关于 Swagger 规范的信息，请访问https ://github.com/wordnik/swagger-core/wiki或 http://swagger.wordnik.com

Git 存储库和问题跟踪器：https ://github.com/hobbeswalsh/flask-sillywalk 文档： http: //flask-sillywalk.readthedocs.org/en/latest/

我为什么要它？

• 您希望您的 API 易于阅读。

• 您希望其他人能够轻松使用您的 API。

• 您想构建一个非常酷的 API 浏览器。

• 现在是星期五晚上，你的朋友刚刚放弃了奶昔。

我如何得到它？

从您最喜欢的外壳中：

$ pip install flask-sillywalk

我该如何使用它？

我很高兴你问。为了使用此代码，您需要首先实例化一个 SwaggerApiRegistry，它将跟踪您的所有 API 端点和文档。

用法：

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

然后，不要使用您习惯于在 Flask 中使用的“@app.route”装饰器，而是使用上面定义的“register”装饰器（如果您正在注册一个描述可能 API 的类，则使用“registerModel”返回值）。

现在我们已经有了一个 API 注册表，我们可以注册一些函数。@register 装饰器，当刚刚给定一个路径（如@app.route）时，将注册一个没有可能参数的 GET 方法。为了记录带有参数的方法，我们可以向@register 函数提供一些参数。

用法：

@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))

现在，如果您导航到http://localhost:5000/api/v1/resources.json，您应该会看到自动 API 文档。请参阅http://localhost:5000/api/v1/cheese.json上所有奶酪端点的文档

还剩下什么？

嗯，很多，其实。本次发布：

• 不支持 XML（但我们真的想要吗？）

• 不支持完整的招摇规范（例如数据模型中的“类型”

• 还有很多。让我知道！