做网站必须要dreamever,天河建设网站方案,wordpress生成二维码,软件开发文档清单自动生成 API 文档的好处不言而喻#xff0c;它可以提供给你的团队或者外部协作者#xff0c;方便 API 使用者准确地调用到你的 API。为了降低手动编写文档带来的错误#xff0c;很多 API 开发者会偏向于寻找一些好的方法来自动生成 API 文档。本文将会介绍一些常用的文档生…自动生成 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.UUIDcase 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.AkkaHttpServerInterpreterimport scala.concurrent.Futureimport akka.http.scaladsl.server.Routeimport scala.concurrent.ExecutionContext.Implicits.globaldef 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.9import 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这里附上一些配置说明
settingdefault valuedescriptionopenapiSwaggerFilebaseDirectory.value / “swagger.yaml”The swagger file with the api definitions.openapiPackagesttp.tapir.generatedThe name for the generated package.openapiObjectTapirGeneratedEndpointsThe name for the generated object.
虽然 Tapir 是一个非常有用的 API 设计和文档工具但它也存在一些缺点
学习成本较高尽管 Tapir 提供了丰富的功能和自动化工具但其高级抽象和复杂的用户界面可能会使初学者感到困惑。因此学习 Tapir 的使用需要一定的时间和经验。依赖 OpenAPI 规范Tapir 基于 OpenAPI 规范因此使用 Tapir 的前提是要对 OpenAPI 规范有一定的了解和理解。如果对 OpenAPI 规范不熟悉可能需要花费额外的时间来学习规范和相关的概念。代码生成可能不准确尽管 Tapir 提供了自动生成客户端代码的功能但生成的代码可能会存在一些问题例如不准确的注释、不规范的代码结构等可能需要开发人员花费额外的时间进行调整和优化。集成可能存在困难由于 Tapir 是一个单独的工具需要与其他开发工具如编辑器、版本控制系统等进行集成可能需要额外的设置和配置可能会增加一些复杂性。
最后感谢每一个认真阅读我文章的人礼尚往来总是要有的这些资料对于【软件测试】的朋友来说应该是最全面最完整的备战仓库虽然不是什么很值钱的东西如果你用得到的话可以直接拿走 这些资料对于【软件测试】的朋友来说应该是最全面最完整的备战仓库这个仓库也陪伴上万个测试工程师们走过最艰难的路程希望也能帮助到你
