使用指南：使用 Swagger 自动生成 API 文档

对Tapir的深度剖析

利用Tapir，一个基于 OpenAPI规范 （也可称作Swagger规范）的开源API设计工具，开发者可以通过一种高层级的抽象方式更轻松地构建和记录RESTful API。

此工具以图形化形式展示API端点及参数，并且配备了丰富的编辑选项及自动文档生成能力，方便开发者生成清晰易懂的说明文件，并支持多种输出格式如OpenAPI和Markdown等，从而适应各种不同的需求。

Tapir不仅限于API的设计与记录，它同样提供API测试和模拟服务，允许开发者模拟API响应进行测试，并且它还能自动生成客户端代码，帮助快速实现API的应用。

选择Tapir的四大理由

类型安全性： 

import sttp.tapir._
import sttp.tapir.generic.auto._
import sttp.tapir.json.circe._
import io.circe.generic.auto._
import java.util.UUID

case class User(name: String)

val paging: EndpointInput[(UUID, Option[Int])] = 
    query[UUID]("start").and(query[Option[Int]]("limit"))

val listUsersEndpoint: PublicEndpoint[(UUID, Option[Int]), Unit, List[User], Any] = 
    endpoint.in("user" / "list").in(paging).out(jsonBody[List[User]])

易于测试： 

维护简单： 

自动化生成代码和文档： 

快速上手Tapir

开始之前先添加相关的库

"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.2.9"

定义一个端点(Endpoint)

case class Status(uptime: Long)

val statusEndpoint: PublicEndpoint[Unit, ErrorInfo, Status, Any] =
   baseEndpoint.in("status").out(jsonBody[Status])

以下是一个例子，演示如何设置分页

import sttp.tapir._
import java.util.UUID

case class Paging(from: UUID, limit: Option[Int])

val paging: EndpointInput[Paging] = 
   query[UUID]("start").and(query[Option[Int]]("limit"))
   .map(input => Paging(input._1, input._2))(paging => (paging.from, paging.limit))

对接Web框架

import sttp.tapir._
import sttp.tapir.server.akkahttp.AkkaHttpServerInterpreter
import scala.concurrent.Future
import akka.http.scaladsl.server.Route
import scala.concurrent.ExecutionContext.Implicits.global

def countCharacters(s: String): Future[Either[Unit, Int]] = 
  Future.successful(Right[Unit, Int](s.length))
  
val countCharactersRoute: Route = 
  AkkaHttpServerInterpreter().toRoute(countCharactersEndpoint.serverLogic(countCharacters))
  
val countCharactersEndpoint: PublicEndpoint[String, Unit, Int, Any] = 
  endpoint.in(stringBody).out(plainBody[Int])
  
val countCharactersRoute: Route = 
  AkkaHttpServerInterpreter().toRoute(countCharactersEndpoint.serverLogic(countCharacters))

自动生成Swagger UI

生成的描述信息可以通过 Swagger UI 或Redoc界面共享给用户。

"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.2.9"

import sttp.tapir._
import sttp.tapir.swagger.bundle.SwaggerInterpreter
import sttp.tapir.server.akkahttp.AkkaHttpServerInterpreter
import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

val myEndpoints: List[AnyEndpoint] = ???

val swaggerEndpoints = 
  SwaggerInterpreter().fromEndpoints[Future](myEndpoints, "My App", "1.0")

val swaggerRoute = 
  AkkaHttpServerInterpreter().toRoute(swaggerEndpoints)

使用yaml生成端点

addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "1.2.9")
Enable the plugin for your project in the build.sbt:
enablePlugins(OpenapiCodegenPlugin)
Add your OpenApi file to the project, and override the openapiSwaggerFile setting in the build.sbt:
openapiSwaggerFile := baseDirectory.value / "swagger.yaml"

下面是一些配置说明：

其他自动生成文档的方法：

• 如何使用 Apifox 自动生成 API 接口文档 - 一份详细指南
• 如何使用YApi自动生成文档