BentoML中为Swagger UI填充默认值的正确方法

在使用BentoML框架开发API服务时，我们经常需要为Swagger UI的"Try it out"功能提供默认值，方便前端开发者快速测试接口。本文将详细介绍如何正确地为BentoML API设置默认参数值。

常见误区

许多开发者会尝试使用Field的examples参数来设置默认值，例如：

@bentoml.api
def predict(
    self,
    companyId: str = Field(examples=["abcde"]),
    qty: int = Field(examples=[10]),
    json: List[Dict] = Field(examples=[mock_features]),
):

这种方法实际上并不能达到预期效果，因为examples参数主要用于生成文档示例，而不是设置默认值。

正确方法

要为Swagger UI的"Try it out"功能设置默认值，应该使用default参数而非examples参数：

@bentoml.api
def predict(
    self,
    companyId: str = Field(default="abcde"),
    qty: int = Field(default=10),
    json: List[Dict] = Field(default=mock_features),
):

原理分析

BentoML底层使用FastAPI来处理API文档生成，而FastAPI的Swagger UI集成会优先使用default参数值作为"Try it out"功能的预填充值。examples参数则主要用于在文档中展示多个可能的输入示例。

最佳实践

1. 对于简单类型参数，可以直接使用Python的默认参数语法：

   @bentoml.api
   def predict(self, qty: int = 10):
   

2. 对于复杂类型或需要额外元数据的参数，使用Field的default参数：

   @bentoml.api
   def predict(self, json: List[Dict] = Field(default=mock_features, description="特征列表")):
   

3. 同时使用default和examples可以提供更好的文档体验：

   @bentoml.api
   def predict(
       self,
       companyId: str = Field(default="abcde", examples=["abcde", "fghij"]),
   ):
   

通过正确使用这些方法，开发者可以显著提升API的易用性和文档质量，使前端团队能够更高效地进行接口测试和集成。