OpenAPI Docs a.k.a Swagger (Coming Soon)

After deploying the application, Batman got multiple queries from the users on how to use the endpoints. Robyn showed him how to generate OpenAPI specifications for his application.

Out of the box, the following endpoints are setup for you:

  • /docs The Swagger UI
  • /openapi.json The JSON Specification

However, if you don't want to generate the OpenAPI docs, you can disable it by passing --disable-openapi flag while starting the application.

python app.py --disable-openapi

How to use?

  • Query Params: The typing for query params can be added as def get(r: Request, query_params=GetRequestParams) where GetRequestParams is a TypedDict
  • Path Params are defaulted to string type (ref: https://en.wikipedia.org/wiki/Query_string)

Basic App

from typing import TypedDict

from robyn import Robyn, OpenAPI
from robyn.openapi import OpenAPIInfo, Contact, License, ExternalDocumentation, Components


app = Robyn(file_object=__file__)


@app.get("/")
async def welcome():
    """welcome endpoint"""
    return "hi"


class GetRequestParams(TypedDict):
    appointment_id: str
    year: int


@app.get("/api/v1/name", openapi_name="Name Route", openapi_tags=["Name"])
async def get(r, query_params=GetRequestParams):
    """Get Name by ID"""
    return r.query_params


@app.delete("/users/:name", openapi_tags=["Name"])
async def delete(r):
    """Delete Name by ID"""
    return r.path_params


if __name__ == "__main__":
    app.start()

How does it work with subrouters?

Subrouters

from typing import TypedDict

from robyn import SubRouter

subrouter = SubRouter(__name__, prefix="/sub")


@subrouter.get("/")
async def subrouter_welcome():
    """welcome subrouter"""
    return "hiiiiii subrouter"


class SubRouterGetRequestParams(TypedDict):
    _id: int
    value: str


@subrouter.get("/name")
async def subrouter_get(r, query_params=SubRouterGetRequestParams):
    """Get Name by ID"""
    return r.query_params


@subrouter.delete("/:name")
async def subrouter_delete(r):
    """Delete Name by ID"""
    return r.path_params


app.include_router(subrouter)

Other Specification Params

We support all the params mentioned in the latest OpenAPI specifications (https://swagger.io/specification/). See an example using request & response bodies below:

Request & Response Body

from robyn.types import JSONResponse

class Initial(TypedDict):
    is_present: bool
    letter: Optional[str]


class FullName(TypedDict):
    first: str
    second: str
    initial: Initial


class CreateItemBody(TypedDict):
    name: FullName
    description: str
    price: float
    tax: float


class CreateResponse(JSONResponse):
    success: bool
    items_changed: int


@app.post("/")
def create_item(request: Request, body=CreateItemBody) -> CreateResponse:
    return {"success": True, "items_changed": 2}

With the reference documentation deployed and running smoothly, Batman had a powerful new tool at his disposal. The Robyn framework had provided him with the flexibility, scalability, and performance needed to create an effective crime-fighting application, giving him a technological edge in his ongoing battle to protect Gotham City.