『FastAPI』编写对接文档

最新推荐文章于 2025-02-10 22:06:17 发布

原创

最新推荐文章于 2025-02-10 22:06:17 发布

· 572 阅读

版权

文章标签：

点赞 + 关注 + 收藏 = 学会了

欢迎订阅《FastAPI中文教程》。

本文简介

本文可在公众号「德育处主任」免费阅读

现在流行前后端分离的开发模式，后端负责处理后台逻辑，用接口的方式和前端交互。而每个接口有什么用？如何调用？要传什么参数？没有一份接口说明书给前端的话就是后端不对了。

FastAPI 其实已经自动帮我们生成对接文档了，但有些接口对接的细节还是需要我们补充。

补充接口细节不止是为了让前端轻松点，对于后端来说也是一份良好的注释。

本文就介绍一下如何写好接口文档。

在《『FastAPI』快速入门》介绍过，运行 FastAPI 项目后，在本地访问 http://127.0.0.1:8000/docs 或者 http://127.0.0.1:8000/redoc 都可以查看到项目对接文档。但这份默认生成的文档比较粗糙，需要我们花点小功夫润色一下。

在实例化 FastAPI 时可以传入一些参数去润色文档。

我拿常用的参数举例说明，工友们看着代码对照截图应该能懂的。

在这里插入图片描述

app = FastAPI(
    title="这是整个文档的大标题",
    description="描述，对这份文档的补充说明",
    version="1.0.0", # API文档的版本号
)

在这里插入图片描述

@app.get("/blogList", summary="播客列表", description="获取播客列表，无需传参进来")
def getBlogList():
    return {
   
        "data": {
   }
    }

有一个 API 的功能是请求博客详情内容，接口是 /blogDetails/{blog_id}，要对 blog_id 的类型、限制、作用进行描述可以这么写。

在这里插入图片描述

from fastapi