Robyn Framework logo
6.1k

OpenAPI 文档（Swagger）

部署应用程序后，蝙蝠侠收到了大量关于如何使用接口的问题。为了解决这一问题，Robyn 向他介绍了 OpenAPI 规范，该规范能够自动生成接口文档。

开箱即用，Robyn 为应用程序提供了以下默认接口：

  • /docs Swagger UI 可视化界面
  • /openapi.json JSON 格式的 OpenAPI 文档

若需要使用自定义的 OpenAPI 配置，您可以：

  • 将 openapi.json 配置文件放在应用程序的根目录中。
  • 或者，将文件路径作为参数传递给 Robyn() 构造函数中的 openapi_file_path 参数（参数的优先级高于文件）。

如果您不希望生成 OpenAPI 文档，可以在启动应用程序时传递 --disable-openapi 参数来禁用该功能。

python app.py --disable-openapi

如何使用？

Basic App

from robyn.robyn import QueryParams

from robyn import Robyn, Request

app = Robyn(
    file_object=__file__,
    openapi=OpenAPI(
        info=OpenAPIInfo(
            title="Sample App",
            description="This is a sample server application.",
            termsOfService="https://example.com/terms/",
            version="1.0.0",
            contact=Contact(
                name="API Support",
                url="https://www.example.com/support",
                email="support@example.com",
            ),
            license=License(
                name="BSD2.0",
                url="https://opensource.org/license/bsd-2-clause",
            ),
            externalDocs=ExternalDocumentation(description="Find more info here", url="https://example.com/"),
            components=Components(),
        ),
    ),
)


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


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


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


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


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

如何在子路由下使用？

Subrouters

from robyn.robyn import QueryParams

from robyn import Request, SubRouter

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


@subrouter.get("/")
async def subrouter_welcome():
    """欢迎来到子路由"""
    return "hiiiiii subrouter"


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


@subrouter.get("/name")
async def subrouter_get(r: Request, query_params: SubRouterGetRequestParams):
    """根据 ID 获取名称"""
    return r.query_params


@subrouter.delete("/:name")
async def subrouter_delete(r: Request):
    """根据名称删除用户"""
    return r.path_params


app.include_router(subrouter)

其他规范参数

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, Body

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


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


class CreateItemBody(Body):
    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 CreateResponse(success=True, items_changed=2)

随着参考文档的成功部署，蝙蝠侠拥有了一个强大的新工具。Robyn 框架为他提供了创建高效打击犯罪应用所需的灵活性、可扩展性和性能，使他在保护哥谭市的持续战斗中获得了技术优势。

使用 Pydantic 模型

如果您已安装 Pydantic（pip install "robyn[pydantic]" 或 pip install "robyn[all]"），可以直接使用 Pydantic BaseModel 类作为处理函数参数的类型注解。Robyn 将自动验证请求体，并且生成丰富的 OpenAPI Schema — 包括属性类型、必填字段、默认值，以及嵌套模型的 $ref 引用。

Pydantic + OpenAPI

from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    email: str
    age: int
    active: bool = True

@app.post("/users", openapi_tags=["Users"])
def create_user(user: UserCreate) -> dict:
    """创建新用户"""
    return {"name": user.name}

有关 Pydantic 验证、嵌套模型、错误响应和 OpenAPI 集成的完整指南，请参阅 Pydantic 集成 页面。

下一步

完成接口文档配置后，蝙蝠侠开始思考如何提升应用程序的并发处理能力。

Robyn 随即向他介绍了多进程执行的相关内容。

多进程