yunstanford/sanic-transmute

Easily document your Sanic API with Swagger UI, Plus param validation and model serialization.

sanic-transmute

Build
Docs
Package

Easily document your Sanic API with Swagger UI, Plus param validation and model serialization.

You can find out more here:

http://sanic-transmute.readthedocs.io/en/latest/

What is sanic-transmute ?

A transmute framework for sanic. This framework provides:

• declarative generation of http handler interfaces by parsing function annotations
• validation and serialization to and from a variety of content types (e.g. json or yaml).
• validation and serialization to and from native python objects, using attrs and schematics.
• autodocumentation of all handlers generated this way, via swagger.

Quick Start

Overview:

Find Examples here:

• example with attrs model.
• example with schematic model.

Simple example with schematics model.

from sanic import Sanic, Blueprint
from sanic.response import json
from sanic_transmute import describe, add_route, add_swagger, APIException
from sanic.exceptions import ServerError
from schematics.models import Model
from schematics.types import IntType


class User(Model):
    points = IntType()


app = Sanic()
bp = Blueprint("test_blueprints", url_prefix="/blueprint")


@describe(paths="/api/v1/user/{user}/", methods="GET")
async def test_transmute(request, user: str, env: str=None, group: [str]=None):
    """
    API Description: Transmute Get. This will show in the swagger page (localhost:8000/api/v1/).
    """
    return {
        "user": user,
        "env": env,
        "group": group,
    }


@describe(paths="/killme")
async def handle_exception(request) -> User:
    """
    API Description: Handle exception. This will show in the swagger page (localhost:8000/api/v1/).
    """
    raise ServerError("Something bad happened", status_code=500)


@describe(paths="/api/v1/user/missing")
async def handle_api_exception(request) -> User:
    """
    API Description: Handle APIException. This will show in the swagger page (localhost:8000/api/v1/).
    """
    raise APIException("Something bad happened", code=404)


@describe(paths="/multiply")
async def get_blueprint_params(request, left: int, right: int) -> str:
    """
    API Description: Multiply, left * right. This will show in the swagger page (localhost:8000/api/v1/).
    """
    res = left * right
    return "{left}*{right}={res}".format(left=left, right=right, res=res)


if __name__ == "__main__":
    add_route(app, test_transmute)
    add_route(app, handle_exception)
    add_route(app, handle_api_exception)
    # register blueprints
    add_route(bp, get_blueprint_params)
    app.blueprint(bp)
    # add swagger
    add_swagger(app, "/api/v1/swagger.json", "/api/v1/")
    app.run(host="0.0.0.0", port=8000)

Simple example with attrs model.

from sanic import Sanic, Blueprint
from sanic.response import json
from sanic_transmute import describe, add_route, add_swagger, APIException
from sanic.exceptions import ServerError
import attr


@attr.s
class User:
    points = attr.ib(type=int)


app = Sanic()
bp = Blueprint("test_blueprints", url_prefix="/blueprint")


@describe(paths="/api/v1/user/{user}/", methods="GET")
async def test_transmute_get(request, user: str, env: str=None, group: [str]=None):
    """
    API Description: Transmute Get. This will show in the swagger page (localhost:8000/api/v1/).
    """
    return {
        "user": user,
        "env": env,
        "group": group,
    }


@describe(paths="/api/v1/user/", methods="POST")
async def test_transmute_post(request, user: User) -> User:
    """
    API Description: Transmute Post. This will show in the swagger page (localhost:8000/api/v1/).
    """
    return user


@describe(paths="/killme")
async def handle_exception(request) -> User:
    """
    API Description: Handle exception. This will show in the swagger page (localhost:8000/api/v1/).
    """
    raise ServerError("Something bad happened", status_code=500)


@describe(paths="/api/v1/user/missing")
async def handle_api_exception(request) -> User:
    """
    API Description: Handle APIException. This will show in the swagger page (localhost:8000/api/v1/).
    """
    raise APIException("Something bad happened", code=404)


@describe(paths="/multiply")
async def get_blueprint_params(request, left: int, right: int) -> str:
    """
    API Description: Multiply, left * right. This will show in the swagger page (localhost:8000/api/v1/).
    """
    res = left * right
    return "{left}*{right}={res}".format(left=left, right=right, res=res)


if __name__ == "__main__":
    add_route(app, test_transmute_get)
    add_route(app, test_transmute_post)
    add_route(app, handle_exception)
    add_route(app, handle_api_exception)
    # register blueprints
    add_route(bp, get_blueprint_params)
    app.blueprint(bp)
    # add swagger
    add_swagger(app, "/api/v1/swagger.json", "/api/v1/")
    app.run(host="0.0.0.0", port=8000)

Development

Build.

./uranium

Run unit tests.

./uranium test

sanic-transmute's Issues

Modify title ,api classification of swagger UI through by code

For example ，“example” and “default”

openapi spec version?

Hi

I don't see which openapi spec this supports. Does this support openapi version 3? With all the polymorphic goodness?

Thanks

Nathan

use sanic.response.json|text

Hello.
it does not seem that it is possible to use sanic.response.json or .text. Look like everything should be json. Is it possible to autorize text return value for some api ?

raise on model mismatch

Hello

When the model describe does not match the actual returned data, the value are actually removed from the returned json, silently. Can we have a mode where it would raise an exception instead ?

Ex:

class MyModel(Model):
    a_name = IntType()

actual returned data by the API:

{
  another_nane: 0
}

Actual returned value:

{}

Expected result:

Error 500: model expects..., actual:...

Add documentation in model

Hello

Sanic-transmute looks very cool, I like the idea of using annotation to describe the model of the API. How can I however add human readable documentation in the model so it will be displayed in the swagger UI (which is very cool!)