Swagger(OpenAPI) API仕様書の自動生成を実現する方法

API仕様書の自動生成は、たくさんのメリットがあります。API仕様書を自動的に生成すると、チームメンバーや他の協業者に便利に共有することが可能になり、APIの使用者がAPIを簡単に呼び出しすることもできるようになります。

現在、多くのAPI開発者はAPI仕様書を自動生成できる方法を探しています。本文では、世界中の開発者に利用されているAPI仕様書の自動生成ツールを皆さんに紹介します。これらのツールを使って、汎用されているSwagger（OpenAPI）仕様書の自動生成が簡単に実現されます。

API仕様書自動生成のメリット

従来のように、手動でAPI仕様書を作成することに比べ、API仕様書の自動生成にはたくさんのメリットがあります。

1. 時間と労力の節約: API仕様書を手動で作成する場合、多くの時間と労力を要することがあります。自動生成ツールを使用することで、APIの詳細な説明やパラメータ、エンドポイントなどの基本的な情報を効率的に生成できます。
2. 一貫性と正確性の向上: 手動で仕様書を作成する場合、文書のスタイルやフォーマットの一貫性を保つのが難しいことがあります。自動生成ツールを使用すると、統一されたスタイルで正確な仕様書を生成することができます。
3. ドキュメンテーションの迅速な更新: APIの変更や更新があった場合、手動で仕様書を更新する必要があります。自動生成ツールを使用すると、変更を自動的に検知し、最新の情報で仕様書を更新できます。これにより、開発者やユーザーは常に最新の情報にアクセスできます。
4. ユーザーフレンドリーなドキュメント: 自動生成ツールを使用すると、仕様書をユーザーフレンドリーにするための追加の機能を提供することができます。例えば、仕様書にリクエストの例やレスポンスのサンプルを自動的に挿入することができます。これにより、開発者やユーザーはAPIの使用方法をより簡単に理解できます。
5. チーム間のコミュニケーションの改善: API仕様書は、開発者やテストエンジニア、プロジェクトマネージャーなど、異なる役割を持つチームメンバー間のコミュニケーションを支援します。自動生成ツールを使用することで、仕様書が明確で一貫性があり、コミュニケーションのミスを減らすことができます。

これらのメリットと利便性により、API仕様書の自動生成は開発者やAPI利用者にとって、非常に価値のあることになると思います。それでは、どうやってAPI仕様書を自動生成すればいいですか？次は、世界中に一番汎用されているAPI仕様のSwagger(OpenAPI) API仕様書の自動生成を実現する方法を皆さんに紹介します。

Swagger(OpenAPI) API仕様書の自動生成ツール

次は、Swagger API仕様書を自動生成するために、利用できるツールを２つ紹介します。1つはTipir（コード）で、もう1つはApidog（ノーコード）です。

⒈Tapir

Tapirは、OpenAPI（以前はSwaggerとして知られていました）をベースとしたAPI仕様記述フォーマットであり、APIの設計とドキュメンテーションを行うためのツールです。

Tapirは、APIのエンドポイント、リクエストおよびレスポンスのデータ構造、認証方法、エラーハンドリングなどの情報を定義するための形式を提供します。これにより、APIの設計とドキュメンテーションのプロセスを効率化し、開発者やユーザーに対して理解しやすいドキュメントを提供することができます。Tapirを使用すると、APIのエンドポイントやリクエスト、レスポンスのスキーマを記述し、エンドポイントごとにパス、HTTPメソッド、パラメータ、ヘッダー、ボディなどを定義することができます。また、認証方法やエラーレスポンスのハンドリングなど、APIに関連するさまざまな情報を追加できます。

APIの設計とドキュメンテーションの機能以外、Tapirは基本のAPIテスト機能も提供しています。この機能により、APIのレスポンスを模擬して、APIを快適にテストすることができるので、開発者は、Tapirのおかげで、より楽にAPIを使用できます。

Tapirを使う理由

統一されたAPI仕様: Tapirは、OpenAPI仕様に基づいており、APIの設計とドキュメンテーションのための統一されたフォーマットを提供します。これにより、開発者やユーザーは一貫性のあるAPI仕様に基づいてコードを記述したり、APIを利用したりすることができます。

ドキュメンテーションの自動生成: Tapirは、API仕様書からドキュメンテーションを自動的に生成する機能を提供します。これにより、開発者は手動でドキュメントを作成する手間を省くことができます。また、自動生成されたドキュメントは常に最新のAPI仕様に基づいているため、正確で最新の情報を提供することができます。

型安全性に対応：型安全性のAPI定義を提供するのは、Tapirの主な特徴の1つです。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]])

テストの自動生成: Tapirは、API仕様書を基にテストコードを自動的に生成する機能も提供します。これにより、開発者はAPIの正しく動作することを保証するためのテストを容易に作成することができます。

エコシステムのサポート: Tapirは、多くの開発ツールやフレームワークと統合することができます。例えば、Tapirを使用して作成したAPI仕様書は、OpenAPIツールのエコシステムで利用することができます。これにより、開発者は他のツールやサービスと連携し、APIの設計や開発をより効率的に行うことができます。

これらの理由から、TapirはAPIの設計とドキュメンテーションのプロセスを効率化し、開発者とユーザーにとって便利なツールとなります。

Tapirを使って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などのUIで文書を共有できます。

"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"

ここで一部設定の説明を添付します。

⒉ノーコードでの実現方法：Apidog

Tapirは非常に優れていたAPI仕様書の自動生成ツールとはいえ、いくつかの欠点があります。

1. 学習曲線の存在: Tapirは、OpenAPI仕様に基づいた比較的高度なツールです。初めて使用する開発者にとっては、学習曲線が存在する可能性があります。特に、APIの設計やセキュリティの概念に不慣れな場合は、追加の学習と理解が必要になる場合があります。
2. 柔軟性の制約: TapirはOpenAPI仕様に準拠しているため、一部の複雑なAPI設計や動作に対して制約がある場合があります。特定の要件やユースケースに対して、Tapirの機能や設定では柔軟性が不足することがあります。その場合は、カスタムコードや拡張機能の組み合わせが必要になるかもしれません。
3. ツールの依存性: Tapirを使用するためには、関連するツールやライブラリに依存する必要があります。例えば、OpenAPIツールセットやScalaの関連ライブラリなどが必要となります。この依存性により、プロジェクトのセットアップやメンテナンスのコストが増える可能性があります。
4. ドキュメンテーションの限定: 自動生成されたドキュメントは、APIの技術的な詳細や機能に焦点を当てています。しかし、ビジネスルールやコンテキストに関するドキュメントを作成する際には、追加の手動作業やカスタマイズが必要になるかもしれません。

確かに、Tapirには以上のような欠点があるので、高度なAPI開発者は、より高度なAPI開発ツールを使う必要があるかと思います。ここでApidogという完成度が抜群のAPI管理ツールをお勧めします。

Apidogは一体化されたAPI管理ツールとして、API仕様書の自動生成は無論のこと、APIの設計、開発、テスト、APIモックなどの機能も非常に強力です。API開発におけて、非常に包括的なソリューションを求めている場合、Apidogは必ず最適なツールだと思います。次は、Apidogの主な機能を皆さんに紹介します。

オンラインドキュメンテーション：API仕様書自動生成

Apidogは、オンラインドキュメンテーションをサポートしています。Apidogを使用すると、綺麗なAPI仕様書を作成したり、自動生成したりすることができます。Apidogの中のAPI仕様書は、Swagger（ OpenAPI）仕様とJson Schemaの仕様に基づいて、ユーザーの定義から生成したものです。このようなAPI仕様書には、エンドポイント、リクエストパラメータ、レスポンスデータ、及びその他の情報が含まれています。特定なニーズがある場合、自動生成されたAPI仕様書をカスタマイズすることもできます。

Apidogで生成したAPI仕様書は、ドキュメントだけではなく、直接にリクエストを送信したり、レスポンスを取得したりすることができるものです。こういう機能により、APIを直接に試すことも可能なので、非常に便利です。

コード自動生成

Apidogは仕様書だけではなく、コードまで直接に生成できます。Apidogも「コード生成」機能は、ほぼ全てのプログラミング言語とフレームワーク（130個強）に対応できます。開発者にとって、コード打ちが不要なので、時間を大幅に節約できます。

インポート/エクスポート機能

Apidogのもう一つの重要な特徴は、そのインポート/エクスポート機能です。ApidogはAPIのエコシステムを絶えず改善し、シームレスな統合を提供することに力を入れています。この機能を通じて、OpenAPI、Markdown、HTMLなどの各種データフォーマットを直接エクスポートしたり、OpenAPI、Postman、YApiなどの異なるデータタイプから直接にインポートたりすることができるので、簡単に業務を続けることができます。