Swagger 自动生成 Api 文档:简化接口文档编写

简介: 自动生成 API 文档的好处不言而喻,它可以提供给你的团队或者外部协作者,方便 API 使用者准确地调用到你的 API。为了降低手动编写文档带来的错误,很多 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.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.

虽然 Tapir 是一个非常有用的 API 设计和文档工具,但它也存在一些缺点:

  1. 学习成本较高:尽管 Tapir 提供了丰富的功能和自动化工具,但其高级抽象和复杂的用户界面可能会使初学者感到困惑。因此,学习 Tapir 的使用需要一定的时间和经验。
  2. 依赖 OpenAPI 规范:Tapir 基于 OpenAPI 规范,因此使用 Tapir 的前提是要对 OpenAPI 规范有一定的了解和理解。如果对 OpenAPI 规范不熟悉,可能需要花费额外的时间来学习规范和相关的概念。
  3. 代码生成可能不准确:尽管 Tapir 提供了自动生成客户端代码的功能,但生成的代码可能会存在一些问题,例如不准确的注释、不规范的代码结构等,可能需要开发人员花费额外的时间进行调整和优化。
  4. 集成可能存在困难:由于 Tapir 是一个单独的工具,需要与其他开发工具(如编辑器、版本控制系统等)进行集成,可能需要额外的设置和配置,可能会增加一些复杂性。

更多自动生成 API 文档的方法。

相关文章
|
6月前
|
存储 JSON API
如何将 Swagger 文档导出为 PDF 文件
你会发现自己可能需要将 Swagger 文档导出为 PDF 或文件,以便于共享和存档。在这篇博文中,我们将指导你完成将 Swagger 文档导出为 PDF 格式的过程。
|
7月前
|
JSON Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
457 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
7月前
|
缓存 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
844 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
|
7月前
|
Java Maven 微服务
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的 maven 依赖
在项目中使用Swagger2工具时,需导入Maven依赖。尽管官方最高版本为2.8.0,但其展示效果不够理想且稳定性欠佳。实际开发中常用2.2.2版本,因其稳定且界面友好。以下是围绕2.2.2版本的Maven依赖配置,包括`springfox-swagger2`和`springfox-swagger-ui`两个模块。
245 0
|
7月前
|
前端开发 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档—— Swagger 简介
第6课介绍了在Spring Boot中集成Swagger2以展示在线接口文档的方法。随着前后端分离架构的发展,API文档成为连接前端与后端开发的重要纽带。然而,代码更新频繁导致文档难以同步维护,Swagger2解决了这一问题。通过Swagger,在线API文档不仅方便了接口调用方查看和测试,还支持开发者实时测试接口数据。本文使用Swagger 2.2.2版本,讲解如何在Spring Boot项目中导入并配置Swagger2工具,从而高效管理接口文档。
253 0
|
6月前
|
XML JSON API
如何从 Swagger 导出 API 文档
Swagger 使这项任务相对简单,允许开发者以各种格式(如 JSON 和 YAML)导出 API 文档。在这篇博文中,我们将详细探讨如何从 Swagger 导出 API 文档。
如何从 Swagger 导出 API 文档
|
9月前
|
API 开发者
通义灵码 API 开发文档自动生成场景DEMO
通义灵码API开发文档自动生成场景DEMO展示了通过自定义指令,大模型能快速根据类代码生成Markdown格式的API文档。文档详细描述API的入参、出参,并可生成测试代码等示例,帮助开发者快速创建美观的API文档。
472 1
|
11月前
|
Java 测试技术 API
详解Swagger:Spring Boot中的API文档生成与测试工具
详解Swagger:Spring Boot中的API文档生成与测试工具
774 4
|
前端开发 Java API
Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版
本文提供了一份详细的Swagger接口文档生成工具的使用教程,包括了导入依赖、配置类设置、资源映射、拦截器配置、Swagger注解使用、生成接口文档、在线调试页面访问以及如何设置全局参数(如token),旨在帮助Java开发者快速上手Swagger。
7400 0
Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版
|
JSON 测试技术 API
Python开发解析Swagger文档小工具
文章介绍了如何使用Python开发一个解析Swagger文档的小工具,该工具可以生成符合httprunner测试框架的json/yaml测试用例,同时还能输出Excel文件,以方便测试人员根据不同需求使用。文章提供了详细的开发步骤、环境配置和使用示例,并鼓励读者为该开源项目贡献代码和建议。
495 1
Python开发解析Swagger文档小工具

热门文章

最新文章