如何在BlackSheep API中使用@docs装饰器添加响应文档？

当然可以给接口响应添加文档，按以下步骤操作就能在控制器里用上@docs装饰器：

1. 暴露全局的docs对象 #

修改app/docs/__init__.py，把原本在configure_docs函数里的局部docs变量改成全局可访问的：

"""
此模块包含API的OpenAPI文档定义。

它暴露了一个docs对象，可用于装饰请求处理器以添加额外信息，用于生成OpenAPI文档。
"""
from blacksheep import Application
from blacksheep.server.openapi.v3 import OpenAPIHandler
from openapidocs.v3 import Info

from app.docs.binders import set_binders_docs
from app.settings import Settings

# 定义全局的docs变量
docs: OpenAPIHandler | None = None

def configure_docs(app: Application, settings: Settings):
    global docs
    docs = OpenAPIHandler(
        info=Info(title=settings.info.title, version=settings.info.version),
        anonymous_access=True,
    )

    # 仅包含路径以"/api/"开头的端点
    docs.include = lambda path, _: path.startswith("/api/")

    set_binders_docs(docs)

    docs.bind_app(app)

2. 在控制器中导入并使用@docs装饰器 #

修改app/controllers/examples.py，导入docs对象，然后用@docs.response装饰器给接口添加响应文档：

"""
使用控制器实现的示例API。
"""
from typing import List, Optional

from blacksheep.server.controllers import Controller, get, post
# 导入全局的docs对象
from app.docs import docs


class ExamplesController(Controller):
    @classmethod
    def route(cls) -> Optional[str]:
        return "/api/examples"

    @classmethod
    def class_name(cls) -> str:
        return "Examples"

    # 添加响应文档：200状态码，描述+JSON schema
    @docs.response(200, "成功获取示例列表", 
                   content={"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}})
    @get()
    async def get_examples(self) -> List[str]:
        """
        获取示例列表。

        Lorem Ipsum Dolor Sit amet
        """
        return list(f"example {i}" for i in range(3))

    # 给POST接口添加响应文档，比如201创建成功
    @docs.response(201, "示例添加成功")
    @post()
    async def add_example(self, example: str):
        """
        添加一个示例。
        """
        return {"status": "ok", "example": example}

3. 验证效果 #

重启API服务后，访问http://localhost:44777/docs就能看到每个接口的响应文档已经更新了。

另外，如果你不需要太复杂的响应schema，BlackSheep也能根据函数的返回类型提示自动生成基础的响应文档，但用@docs.response可以添加自定义的描述、状态码和更详细的schema定义。

内容的提问来源于stack exchange，提问作者Ocaso Protal