最佳实践：Swagger 自动生成 Api 文档

目录

Tapir 介绍

为什么使用 Tapir

快速使用 Tapir

添加依赖

定义一个端点(Endpoint)

生成 Swagger ui

根据 yaml 生成 endpoint

---

自动生成 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 n