Índice
Definir um endpoint (Endpoint)
Gerar interface do usuário Swagger
Gere endpoint de acordo com yaml
Os benefícios de gerar automaticamente a documentação da API são evidentes. Ela pode ser fornecida à sua equipe ou colaboradores externos, para que os usuários da API possam chamar sua API com precisão . Para reduzir erros causados pela escrita manual de documentos, muitos desenvolvedores de API preferirão encontrar boas maneiras de gerar documentos de API automaticamente. Este artigo apresentará algumas ferramentas de geração de documentos comumente usadas: Tapir, uma ferramenta de código aberto, e Apifox, um produto comercial.
Introdução
Tapir é uma ferramenta de design e documentação de API de código aberto, baseada na especificação OpenAPI (também conhecida como especificação Swagger) e fornece um nível mais alto de abstração que pode ajudar os desenvolvedores a projetar e documentar APIs RESTful com mais facilidade .
Tapir exibe os diferentes endpoints e parâmetros da API de forma visual e fornece funções de edição avançadas e ferramentas de geração automática de documentos de API, que podem gerar documentos fáceis de ler e entender, e também fornece uma variedade de formatos de exportação (como como Especificação OpenAPI, Markdown, etc.) para atender a diferentes necessidades.
Além do design e da documentação da API, o Tapir também fornece recursos de teste e simulação para APIs, que podem simular respostas da API e testá-las. Ele também oferece a capacidade de gerar código de cliente automaticamente, permitindo que os desenvolvedores usem a API mais rapidamente.
Por que usar o Tapir
1. Fornecer segurança de tipo: Um dos principais recursos do Tapir é fornecer definições de API com segurança de tipo. Você pode usar o verificador de tipo forte do Scala para verificar a exatidão das definições de API, reduzindo assim os erros de tempo de execução causados por definições de API incorretas.
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. Facilidade de teste : como o Tapir fornece definições de API com segurança de tipo, você pode usar a estrutura de teste do Scala para escrever facilmente casos de teste e garantir que sua API possa ser executada corretamente em várias circunstâncias. Isso pode reduzir erros e bugs no processo de desenvolvimento e melhorar a eficiência do desenvolvimento.
3. Facilidade de manutenção: Tapir fornece uma definição de API fácil de manter porque decompõe a definição de API em partes independentes e combináveis. Isso significa que você pode atualizar facilmente partes da API sem afetar toda a definição da API.
4. Gerar código de cliente e servidor: Tapir pode ser usado para converter definições de API em vários tipos de código de cliente e servidor, incluindo cliente e servidor HTTP, cliente e servidor Scala e Java, etc. Isso reduz o esforço de escrever manualmente o código do cliente e do servidor, ao mesmo tempo que reduz o potencial de erros e bugs.
5. Gerar documentação de API automaticamente: Tapir fornece um método para gerar documentação de API automaticamente, o que torna a criação de documentação de API simples e fácil de manter. Você pode optar por gerar documentação a partir da definição de API em tempo de execução ou agrupar a definição de API com a documentação em tempo de construção.
Use Tapir rapidamente
adicionar dependências
"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.2.9"Definir um endpoint (Endpoint)
case class Status(uptime: Long)
val statusEndpoint: PublicEndpoint[Unit, ErrorInfo, Status, Any] =
baseEndpoint.in("status").out(jsonBody[Status])A seguir está um exemplo de paginação
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))Estrutura web integrada
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))Gerar interface do usuário Swagger
As descrições geradas podem ser compartilhadas usando interfaces de usuário como Swagger ou 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)Gere endpoint de acordo com 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"Aqui estão algumas instruções de configuração:
| contexto | valor padrão | descrição |
|---|---|---|
| openapiSwaggerFile | baseDirectory.value/“swagger.yaml” | O arquivo swagger com as definições da API. |
| openapiPackage | sttp.tapir.gerado | O nome do pacote gerado. |
| openapiObject | TapirGeneratedEndpoints | O nome do objeto gerado. |
Embora o Tapir seja uma ferramenta muito útil para design e documentação de APIs, ele tem algumas desvantagens:
- Alto custo de aprendizado: embora o Tapir ofereça uma variedade de recursos e ferramentas de automação, suas abstrações de alto nível e interface de usuário complexa podem confundir os iniciantes. Portanto, aprender a usar o Tapir exige tempo e experiência.
- Confie na especificação OpenAPI : Tapir é baseado na especificação OpenAPI, portanto, o pré-requisito para usar o Tapir é ter um certo conhecimento e compreensão da especificação OpenAPI. Se você não estiver familiarizado com a especificação OpenAPI, talvez precise dedicar mais tempo aprendendo a especificação e os conceitos relacionados.
- A geração de código pode ser imprecisa: embora o Tapir forneça a função de gerar automaticamente o código do cliente, pode haver alguns problemas no código gerado, como comentários imprecisos, estrutura de código irregular, etc., que podem exigir que os desenvolvedores gastem mais tempo Ajustando e otimizando .
- A integração pode ser difícil: como o Tapir é uma ferramenta separada, ele precisa ser integrado a outras ferramentas de desenvolvimento (como editores, sistemas de controle de versão, etc.), o que pode exigir instalação e configuração adicionais, o que pode adicionar alguma complexidade.
A seguir estão os melhores recursos de tutoriais de aprendizagem que coletei. Embora não sejam muito valiosos, se você apenas precisar deles, pode deixar uma mensagem na área de comentários [777] e simplesmente retirá-los
Amigos que desejam obter informações, curta + comente + favorito , triplo!
Depois de três vezes seguidas , enviarei mensagens privadas uma por uma na área de comentários ~