1 前言
最近着手一个小项目示例的时候，会遇到关于文档对接小问题，其实我个人不是非常喜欢Fastapi内置的文档，因为可能还用的不是太熟的缘故，所以没细究很多问题。以下是我的在进行项目开发的时候，关于文档上遇到一些小问题细节的处理问题总结，也是对以往项目的一些小问题回顾总结。
- schemas模型中使用依赖和非依赖区别
- schema_extra 配置显示的问题
- 参数注释说明描述问题
- response_description换行问题
2 文档效果显示
3 问题细解
问题1：schemas模型使用依赖或非依赖方式区别
在进行API接口定义过程中，我们的需要对我们的提交参数进行校验的时候，通常我的个人习惯进行，所有会有下面的定义方式：
from framecore.libs.responses.json_response import Success, Fail
from rights.apis.v1.goods import api_router
from fastapi import BackgroundTasks, Body, Depends, Query
from pydantic import BaseModel
class ExchangeGoodsForm2(BaseModel):
code: str
rightcode: str
token2222: str = Query(None, description="授权码")
schema_extra = {
"code": "要兑换的商品编222码",
"rightcode": "要消耗的权益码",
}
# 描述和description会有冲突，所以只能有一个存在
@api_router.get("/exchange1", summary='确定兑换或直充')
def exchange_goods(forms: ExchangeGoodsForm2 = Depends()):
return Success(message='操作处理已提交!')
# 描述和description会有冲突，所以只能有一个存在
@api_router.get("/exchange2", summary='确定兑换或直充')
def exchange_goods(forms: ExchangeGoodsForm2):
return Success(message='操作处理已提交!')
代码区别主要在于：
- def exchange_goods(forms: ExchangeGoodsForm2 = Depends()): 使用了依赖注入
- def exchange_goods(forms: ExchangeGoodsForm2): 没有使用依赖注入
不同的定义产生的问题现象:
使用了依赖注入
没有使用了依赖注入
问题结论
如果使用依赖注入方式，则所有的参数请求都会转为请求参数query的方式进行提交。没有使用的依赖注入的话，则参数是使用Body的方式方式进行提交。
问题2：schema_extra 配置显示的问题
问题描述，如果使用了依赖输入方式来对ExchangeGoodsForm进行处理的时候，则我们的schema_extra配置会失效，不显示。
class ExchangeGoodsForm(BaseModel):
# 要兑换的商品编码
code: str
# 要消耗的权益码
rightcode: str
class Config:
schema_extra = {
"example":
{
"token": "用户登入授权Token",
"code": "要兑换的商品编码",
"rightcode": "要消耗的权益码",
}
}
通用的解决的方式：
class ExchangeGoodsForm(BaseModel):
# 要兑换的商品编码
code: str
# 要消耗的权益码
rightcode: str
schema_extra = {
"example":
{
"token": "用户登入授权Token",
"code": "要兑换的商品编码",
"rightcode": "要消耗的权益码",
}
}
问题3：关于参数注释说明描述问题
如果我们的需要在文档上查看关于文档一些注释描述的说明，则需要配置description
@api_router.get("/exchange1", summary='确定兑换或直充',description='方法注释说明')
def exchange_goods(forms: ExchangeGoodsForm2 = Depends()):
return Success(message='操作处理已提交!')
但是如果描述的文字比较多，且换行之类的什么时候，则不建议使用，建议使用下列的方式来处理：
@api_router.get("/exchange1", summary='确定兑换或直充')
def exchange_goods(forms: ExchangeGoodsForm2 = Depends()):
"""
关于签名算法，请参考[加粗 Issue](https://xxxxxxxx "加粗 Issue")。
[更详细介绍](https://mp.weixin.qq.com/s/lM808MxUu6tp8zU8SBu3sg)
接口描述：
- 用于登入的时候发送登入验证码
请求参数体：
- token 登入手机号码 **必填**
- rightcode 要消耗的权益码 **必填**
- code 验证码 可选
响应报文体：
- message 请求操作结果描述
- code 请求操作内部响应码
- success 请求结果是否处理成功 true 成功 False失败
- result 返回请求结果内容
"""
return Success(message='操作处理已提交!')
PS:方法注释和description会有冲突，所以只能有一个存在，同时存在的时候会已description优先
上面的效果显示：
问题4：response_description换行问题
如果我们的需要对响应报文做更详细的描述显示在文档，除了通过上面的再方法里添加之外，还可以显示再我们的response_description，但是如果要显示的换行的话，则需要按如下的方式处理。
@api_router.get("/exchange", summary='确定兑换或直充', response_description=""
"返回结果描述：\n\n"
"message: 请求操作结果描述\n\n"
"code: 请求操作内部响应码\n\n"
"success: 请求结果是否处理成功\n\n"
"result: 返回请求结果内容\n\n"
"at_types：0： 兑换码 1：直充\n\n"
"remaskinfo：兑换描述\n\n"
"excode：如果是兑换码的话 就返回值 否则为空\n\n"
"")
def exchange_goods(forms: ExchangeGoodsForm2=Depends()):
'''
参数说明\n
- code: 要兑换的商品编码【必填】\n
- rightcode: 要消耗的权益码【必填】\n
- token: 登入成功的时候返回的授权码【必填】\n
'''
return Success(message='操作处理已提交!')
这种描述其实不是非常的优雅，但是为了显示的话，也看自己需要咯，最终结果是：
总结
以上仅仅是个人结合自己的实际需求，做学习的实践笔记！如有笔误！欢迎批评指正！感谢各位大佬！
结尾
END
简书：www.jianshu.com/u/d6960089b…
公众号：微信搜【小儿来一壶枸杞酒泡茶】
小钟同学 | 文 【欢迎一起学习交流】| QQ：308711822
