The benefits of automatically generating API documentation are self-evident. It can provide your team or external collaborators with easy access to your API, enabling users to make accurate calls to your API. In order to reduce errors caused by manual documentation, many API developers prefer to find good ways to automatically generate API documentation.
This article will introduce some commonly used documentation generation tools: the open-source tool Tapir and the professional product Apidog.
Tapir is an open-source API design and documentation tool that is based on the OpenAPI specification (also known as the Swagger specification) and provides higher-level abstractions to help developers design and document RESTful APIs more easily.
Tapir displays different endpoints and parameters in a visual way, offering multiple edition functions and automation API documentation generation tools.
Tapir displays the different endpoints and parameters of an API in a visual way and provides rich editing features and automated API documentation generation tools that can generate easily readable and understandable documents. It also offers various export formats (such as OpenAPI specification, Markdown, etc.) to meet different needs. In addition to API design and documentation, Tapir also provides testing and simulation functions for APIs, allowing developers to simulate API responses and conduct testing. It also offers the ability to automatically generate client code, which enables developers to use the API more quickly.
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]])
"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])
Here is an example of pagination:
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))
Integrate with a web framework.
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))
The generated description can be shared through a user interface such as Swagger or 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)
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"
There are setting description attachments.
| 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. |
From in-depth using Tapir, some limitation are as follows. Despite providing rich functionality and automation tools, Tapir's advanced abstractions and complex user interface may be confusing for beginners. Moreover, Tapir is based on the OpenAPI specification, so using Tapir requires some understanding and knowledge of the OpenAPI specification. If you are not familiar with the OpenAPI specification, you may need to spend additional time learning the specification and related concepts.
Although Tapir provides the functionality of automatically generating client-side code, the generated code may have some problems, such as inaccurate comments and non-standard code structure. Since Tapir is a standalone tool, it needs to be integrated with other development tools (such as editors and version control systems), which may require additional settings and configurations and may add some complexity.
For professional API developers or development teams accustomed to the Design First approach, we recommend the more user-friendly API collaboration platform, Apidog. Apidog is a comprehensive API management platform that provides API documentation, API debugging, API mock, and API automation testing capabilities, and can solve data synchronization problems between multiple systems.
Apidog is a solution to interface management problems, supporting use case management, data model definition, automatic verification of data structures during debugging, and visualization of setting assertions and extracting variables.
In addition to basic capabilities, Apidog also provides many features that not only satisfy developers' daily API development, debugging, and testing scenarios but also support developers in managing and sharing API documentation and generating code based on API documentation.
Apidog provides an online platform for creating, testing, and managing APIs, making it easier for developers to use APIs. One of Apidog's main features is its support for online API documentation.
With Apidog, you can easily create and maintain clear and comprehensive documentation for your APIs. The documentation is generated based on API definitions and follows the OpenAPI and JSON Schema standards. The documentation includes detailed information about endpoints, request parameters, response data, and other relevant information.
You can also customize the documentation to meet your specific needs and easily share it with others. Apidog's documentation is not just text; it also includes interactive features such as trying out the server, viewing request and response examples, and more. These features help developers better understand and quickly test APIs. Apidog also provides real-time updates, so any changes made to the API will be promptly reflected in the online documentation.
Apidog also has the ability to automatically generate code, generating code snippets for almost all popular programming languages and frameworks (over 130 in total). This can save developers a lot of time and effort as they do not have to start from scratch. Code templates can be customized according to developers' preferences, making it more flexible.
Another important feature of Apidog is its import/export functionality. Apidog is committed to continuously improving the API ecosystem by providing seamless integration. With this feature, you can directly export various data formats such as OpenAPI, Markdown, HTML, and more for further API work. You can also import different data types such as OpenAPI, Postman, YApi, and more, making it easier to migrate projects.
