ベストプラクティス: Swagger は API ドキュメントを自動的に生成します

API ドキュメントを自動生成する利点は自明であり、チームまたは外部の共同作業者に提供できるため、API ユーザーが API を正確に呼び出すことができます。ドキュメントを手動で作成することによって発生するエラーを減らすために、多くの API 開発者は、API ドキュメントを自動的に生成するいくつかの優れた方法を見つけることを好みます。この記事では、一般的に使用されるいくつかのドキュメント生成ツール、オープンソースツールである Tapir と商用製品である Apifox を紹介します。

導入

Tapir は、オープンソースの API 設計およびドキュメント化ツールであり、 OpenAPI 仕様(Swagger 仕様とも呼ばれます)に基づいており、開発者が RESTful API をより簡単に設計およびドキュメント化できるようにする、より高いレベルの抽象化を提供します。

Tapir は、API のさまざまなエンドポイントとパラメーターを視覚的に表示し、読みやすく理解しやすいドキュメントを生成できる豊富な編集機能と自動 API ドキュメント生成ツールを提供します。また、さまざまなエクスポート形式 ( OpenAPI 仕様、Markdown など) を使用して、さまざまなニーズに対応します。

API の設計とドキュメントに加えて、Tapir は API のテスト機能とモック機能も提供しており、API 応答をシミュレートしてテストできます。また、クライアントコードを自動的に生成する機能も提供され、開発者が API をより迅速に使用できるようになります。

Tapirを使用する理由

1. タイプセーフの提供: Tapir の主な機能の 1 つは、タイプセーフな 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 が正しく実行できることを確認できます。これにより、開発プロセスにおけるエラーやバグが削減され、開発効率が向上します。

3. メンテナンスの容易さ: Tapir は、API 定義を独立した構成可能な部分に分解するため、メンテナンスが容易な API 定義を提供します。これは、API 定義全体に影響を与えることなく、API の一部を簡単に更新できることを意味します。

4. クライアントおよびサーバーコードの生成: Tapir を使用して、API 定義を、HTTP クライアントおよびサーバー、Scala および Java クライアントおよびサーバーなどを含むさまざまなタイプのクライアントおよびサーバーコードに変換できます。これにより、クライアントとサーバーのコードを手動で記述する労力が軽減され、エラーやバグの可能性が減ります。

5. API ドキュメントの自動生成: Tapir は、API ドキュメントを自動的に生成する方法を提供します。これにより、API ドキュメントの作成が簡単になり、保守が容易になります。実行時に API 定義からドキュメントを生成するか、ビルド時に API 定義をドキュメントにバンドルするかを選択できます。

バクを素早く使用する

依存関係を追加する

"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.2.9"

エンドポイントを定義する (エンドポイント)

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に従ってエンドポイントを生成する

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"

以下にいくつかの構成手順を示します。

設定	デフォルト値	説明
openapiSwaggerファイル	BaseDirectory.value / “swagger.yaml”	API 定義を含む Swagger ファイル。
openapiパッケージ	sttp.tapir.generated	生成されたパッケージの名前。
openapiオブジェクト	TapirGeneratedエンドポイント	生成されたオブジェクトの名前。

Tapir は API の設計とドキュメント化に非常に便利なツールですが、いくつかの欠点があります。

高い学習コスト: Tapir は豊富な機能と自動化ツールを提供しますが、その高レベルの抽象化と複雑なユーザーインターフェイスは初心者を混乱させる可能性があります。したがって、Tapir の使用方法を習得するには時間と経験が必要です。
OpenAPI 仕様に依存する: Tapir は OpenAPI 仕様に基づいているため、Tapir を使用するための前提条件は、OpenAPI 仕様についての一定の知識と理解を持っていることです。OpenAPI 仕様に詳しくない場合は、仕様と関連する概念を学ぶために余分な時間を費やす必要があるかもしれません。
コード生成が不正確になる可能性がある: Tapir はクライアントコードを自動生成する機能を提供しますが、生成されたコードには不正確なコメントや不規則なコード構造などの問題が発生する可能性があり、開発者は調整と最適化に余分な時間を費やす必要がある可能性があります。。
統合は難しい場合があります。Tapir は別個のツールであるため、他の開発ツール (エディター、バージョン管理システムなど) と統合する必要があり、追加のセットアップと構成が必要になる可能性があり、複雑さが増す可能性があります。

以下は、私が収集したより優れた学習チュートリアルリソースです。あまり価値はありませんが、必要な場合は、コメントエリア [777] にメッセージを残して、そのまま持ち帰ってください。

情報が欲しいお友達はいいね＋コメント＋お気に入りのトリプルをお願いします！

3回連続でコメント欄に個別メッセージを送ります〜