如何在tapir端点定义中记录JSON请求体模式

Question

我使用tapir定义了一系列端点，如下所示：

    def thingModifyState[M: Encoder: Decoder: Schema] =
      endpoint.put
      .name(s"Modify state of a $name Thing")
      .description("Apply a modification object to a Thing")
      .in("state")
      .in(this.name.description("Type of Thing"))
      .in(
        path[String Refined And[MatchesRegex["^[a-z0-9_]+$"], MaxSize[64]]]
          .description("Name of Thing")
          .name("thing")
      )
      .in(jsonBody[M].description("Object describing modification"))
      .errorOut(
        statusCode
          .description(StatusCode(404), "Thing does not exist")
      )
      .tag(name)

然后使用thingModifyState定义多个端点：

blueRoutes.thingModifyState[things.models.blue.StateChange]
redRoutes.thingModifyState[things.models.red.StateChange]

blue.StateChange对象的定义如下：

object StateChange {
  implicit val config: Configuration = Configuration.default.withSnakeCaseMemberNames
  implicit val thingStateEncoder: Encoder[StateChange] = deriveEncoder(derivation.renaming.snakeCase)
  implicit val thingStateDecoder: Decoder[StateChange] = deriveDecoder(derivation.renaming.snakeCase)
  implicit val thingStateSchema: Schema[StateChange] = Schema.derived
}

/**
  * Specifies a change to the Thing's state
  *
  * @param counterChange negative or positive increment of the counter
  * @param resetTimestamp new timestamp value
  */
case class StateChange(counterChange: Long, resetTimestamp: Long)

当生成文档(使用redoc)时，“请求体模式”部分如下所示：

​

​

jsonBody的总体描述(“对象描述修改”)在文档中可见，但我想包括对jsonBody字段(counter_change / reset_timestamp)及其类型的描述。

我不希望从StateChange获得scaladoc定义，但是现在我还不知道如何将jsonBody字段的描述输入到输出文档中。我是否需要手动派生架构，并以某种方式包含描述？

编辑:我怀疑这一点：https://github.com/softwaremill/tapir/issues/247是相关的，但是问题末尾的文档链接(https://tapir-scala.readthedocs.io/en/latest/endpoint/customtypes.html#customising-derived-schemas)链接到一个不再存在的锚点。我还没找到它的新位置！

EDIT2:啊，也许链接现在在这里：https://tapir.softwaremill.com/en/latest/endpoint/schemas.html#customising-derived-schemas。它提到使用@description注释，但缺少关于这些注释用于派生模式的说明/示例。

EDIT3:我本来希望有这样的东西：

import sttp.tapir.EndpointIO.annotations.description

case class StateChange(
  @description("negative or positive increment of the counter") counterChange: Long, 
  @description("new timestamp value") resetTimestamp: Long
)

..。但没什么用。

Answer 1

在这里的文档之后：https://tapir.softwaremill.com/en/latest/endpoint/schemas.html#customising-derived-schemas，像下面这样定义case类：

import sttp.tapir.Schema.annotations._

case class StateChange(
                        @description("negative or positive increment of the counter") counterChange: Long,
                        @description("new value for reset timestamp") resetTimestamp: Long
                      )

请注意，您需要从sttp.tapir.Schema.annotations导入注释，而不是从我问题中提到的位置导入注释。