自动生成 API 文档的好处不言而喻，它可以提供给你的团队或者外部协作者，方便 API 使用者准确地调用到你的 API。为了降低手动编写文档带来的错误，很多 API 开发者会偏向于寻找一些好的方法来自动生成 API 文档。本文将会介绍一些常用的文档生成工具：开源工具 Tapir，商业化产品 Apifox。
Tapir 介绍
Tapir 是一个开源的 API 设计和文档工具，它基于 OpenAPI 规范（也称为 Swagger 规范）并提供了更高级别的抽象，可以帮助开发人员更轻松地设计和文档化 RESTful API。
Tapir 以可视化的方式显示 API 的不同端点和参数，并提供了丰富的编辑功能和自动化的 API 文档生成工具，可以生成易于阅读和理解的文档，同时也提供了多种导出格式（如 OpenAPI 规范、Markdown 等）以满足不同需求。
除了 API 设计和文档，Tapir 还提供了针对 API 的测试和模拟功能，可以模拟 API 的响应并进行测试。它还提供了自动生成客户端代码的功能，使得开发人员可以更快速地使用 API。
为什么使用 Tapir
1、提供类型安全：Tapir 的主要特点之一是提供类型安全的 API 定义。你可以使用 Scala 的强类型检查器来检查 API 定义的正确性，从而减少由于 API 定义不正确而导致的运行时错误。
import sttp.tapir._import sttp.tapir.generic.auto._import sttp.tapir.json.circe._import io.circe.generic.auto._import java.util.UUIDcase class User(name: String)val paging: EndpointInput[(UUID, Option[Int])] = query[UUID]("start").and(query[Option[Int]]("limit"))// we can now use the value in multiple endpoints, e.g.:val listUsersEndpoint: PublicEndpoint[(UUID, Option[Int]), Unit, List[User], Any] = endpoint.in("user" / "list").in(paging).out(jsonBody[List[User]])
2、易于测试：由于 Tapir 提供了类型安全的 API 定义，你可以使用 Scala 的测试框架来轻松地编写测试用例，并确保你的 API 在各种不同的情况下都能正确运行。这可以减少开发过程中的错误和 Bug，提高开发效率。
3、易于维护：Tapir 提供了一种易于维护的 API 定义方式，因为它将 API 定义分解成独立的、可组合的部分。这意味着你可以轻松地更新 API 的某些部分，而不必影响整个 API 的定义。
4、生成客户端和服务器代码：使用 Tapir 可以将 API 定义转换为各种不同类型的客户端和服务器代码，包括 HTTP 客户端和服务器、Scala 和 Java 客户端和服务器等。这可以减少手动编写客户端和服务器代码的工作量，同时减少错误和 Bug 的可能性。
5、自动生成 API 文档：Tapir 提供了一种自动生成 API 文档的方法，这使得 API 文档的创建变得简单且容易维护。你可以选择在运行时从 API 定义生成文档，或者在构建时将 API 定义与文档绑定在一起。
快速使用 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 或 Redoc 等用户界面进行文档分享。
"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.2.9"
import sttp.tapir._import sttp.tapir.swagger.bundle.SwaggerInterpreterimport sttp.tapir.server.akkahttp.AkkaHttpServerInterpreterimport scala.concurrent.Futureimport scala.concurrent.ExecutionContext.Implicits.globalval myEndpoints: List[AnyEndpoint] = ???// first interpret as swagger ui endpoints, backend by the appropriate yamlval swaggerEndpoints = SwaggerInterpreter().fromEndpoints[Future](myEndpoints, "My App", "1.0")// add to your akka routesval swaggerRoute = AkkaHttpServerInterpreter().toRoute(swaggerEndpoints)
根据 yaml 生成 endpoint
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"
这里附上一些配置说明：
| setting | default value | description |
|---|---|---|
| openapiSwaggerFile | baseDirectory.value / “swagger.yaml” | The swagger file with the api definitions. |
| openapiPackage | sttp.tapir.generated | The name for the generated package. |
| openapiObject | TapirGeneratedEndpoints | The name for the generated object. |
免费好用的商业产品：Apifox
虽然 Tapir 是一个非常有用的 API 设计和文档工具，但它也存在一些缺点：
- 学习成本较高：尽管 Tapir 提供了丰富的功能和自动化工具，但其高级抽象和复杂的用户界面可能会使初学者感到困惑。因此，学习 Tapir 的使用需要一定的时间和经验。
- 依赖 OpenAPI 规范：Tapir 基于 OpenAPI 规范，因此使用 Tapir 的前提是要对 OpenAPI 规范有一定的了解和理解。如果对 OpenAPI 规范不熟悉，可能需要花费额外的时间来学习规范和相关的概念。
- 代码生成可能不准确：尽管 Tapir 提供了自动生成客户端代码的功能，但生成的代码可能会存在一些问题，例如不准确的注释、不规范的代码结构等，可能需要开发人员花费额外的时间进行调整和优化。
- 集成可能存在困难：由于 Tapir 是一个单独的工具，需要与其他开发工具（如编辑器、版本控制系统等）进行集成，可能需要额外的设置和配置，可能会增加一些复杂性。
对于专业的 API 开发者，或者是习惯 Design First 模式的开发团队，我们推荐体验更佳的 API 一体化协作平台 Apifox。
Apifox 是一个综合性的 API 管理平台，提供了 API 文档、API 调试、API Mock、API 自动化测试等功能，并能够解决多个系统之间的数据同步问题。Apifox 是一个解决接口管理问题的解决方案，它支持用例管理、数据模型定义、调试时自动校验数据结构、可视化设置断言和提取变量等功能。
为什么使用 Apifox
除了基础能力，Apifox 还提供了非常多的特性，除了满足开发者对于日常 API 开发、调试、测试场景，还支持开发者管理与分享 API 文档、也能够基于 API 文档自动生成代码。
在线 API 文档
Apifox 提供了一个用于创建、测试和管理 API 的在线平台，旨在让开发人员可以更轻松地使用 API。Apifox 主要特性之一是它支持在线 API 文档。使用 Apifox，你可以轻松地为你的 API 创建和维护清晰全面的文档。该文档是根据 API 定义自动生成的，并遵循 OpenAPI 和 JSON Schema 标准。该文档包括了有关端点、请求参数、响应数据和其它相关的详细信息。你也可以自定义文档来满足你的特定需求，并且可以方便地与其他人共享。
Apifox 的文档不仅仅是文本，它还包括交互功能，例如试用服务端、查看请求和响应示例等等。这些特性帮助开发人员更容易理解并快速试用 API。Apifox 还提供了更新功能，因此对 API 所做的任何更改都会及时反应在在线文档中。
代码自动生成
Apifox 还具有代码自动生成功能，它可以生成几乎所有流行的编程语言和框架（总计超过 130 种）的代码片段。这可以为开发人员节省大量时间和精力，因为不必从头开始编写代码。代码模版可以根据开发者的喜好进行定制，更加灵活。
导入/导出功能
Apifox 的另一个重要特性就是它的导入/导出功能。Apifox 致力于不断完善 API 生态系统提供无缝集成。通过该功能，你可以直接导出 OpenAPI、Markdown、HTML 等各种数据格式类型从而进行下一步 API 工作；也可以导入 OpenAPI、Postman、YApi 等等不同数据类型，方便进行项目迁移。这有助于保持工作上的连续性，并减少手动输入数据所花费的时间。
IDEA 插件自动生成文档
值得一提的是 Apifox Helper， 它 是一款 IDEA 插件，帮助开发者自动解析代码注释并快速生成 API 文档的便捷工具。 Apifox Helper 是基于 javadoc（Java）、KDoc（Kotlin）、ScalaDoc（Scala）解析 API 文档，支持 Spring Boot、Swagger、JAX-RS 等协议框架，基本可以实现代码零入侵自动生成接口文档 。 在 IDEA 中使用 Apifox Helper 可以一键同步文档到 Apifox 项目中，开发者无需切换工具，即可更新同步文档给团队内其他人员。 自动解析注释、快速同步文档、IDEA 内调试、Apifox 便捷团队协作。
自动生成 API 文档，就用 Apifox。