Aug
How to Generate Swagger UI with Akka HTTP
If you’re working with Akka HTTP, the powerful toolkit and runtime for building web and HTTP-based applications in Scala, you’re likely aware of the importance of clear and interactive API documentation. This is where Swagger UI comes into play.
Swagger is an open-source framework that facilitates the design, documentation, and testing of RESTful APIs. It provides a set of tools and specifications that allow developers to describe their APIs in a standardized format, making it easier to understand and interact with them. If you want to add swagger to your project, here are a few steps you need to follow:
STEP-1
Add Dependency:
Firstly, we need to add swagger-akka–http dependency in our application’s build.sbt.
“com.github.swagger-akka-http” % “swagger-akka-http_2.11” % “0.14.0”
STEP-2
Add Swagger UI:
Adding Swagger UI to the site is quite easy, you simply need to drop the static site files into the resource’s directory of your project. You can either download these UI files (HTML/CSS) from swagger website or use the existing files from the service in which swagger is implemented. You can also change these files according to your requirements.
To read these files from the resource directory, follow the below path –
getFromResourceDirectory(“swagger-ui”)
STEP-3
Add Route Property :
Next step is adding routes property in your application. This property should be designed to be added to other existing routes. Afterward, create a new package called “swagger” within the “controller” package. Inside this “swagger” package, your objective is to develop a class named “Swagger.scala” that will specifically manage Swagger-related functionalities.
This class basically contains the configuration properties of the swagger.
The Swagger.scala contains a routes property which can be concatenated along with existing akka-http routes.
case class Swagger(system: ActorSystem) extends SwaggerHttpService {
val config = ConfigFactory.load()
val API_URL = config.getString(“swagger.api.url”)
val BASE_PATH = config.getString(“swagger.api.base.path”)
val PROTOCOL = config.getString(“swagger.api.scheme.protocol”)
override def apiClasses: Set[Class[_]] = Set(classOf[Base])
override val host = API_URL
override val basePath = BASE_PATH
override def schemes: List[Scheme] = List(Scheme.forValue(PROTOCOL))
override def apiDocsPath: String = “api-docs”
val apiKey = new ApiKeyAuthDefinition(“api_key”, QUERY)
override val securitySchemeDefinitions: Map[String, ApiKeyAuthDefinition] = Map(“apiKey” -> apiKey)
override def info: Info =
new Info(
“Swagger Akka http demo application….”,
“1.0”,
“Swagger API”,
“”,
None,
None,
Map.empty)
}
STEP-4
DOCUMENT THE ROUTES-
To document the routes, create a respective trait inside the swagger package of the class that you want to document. For example, if you want to document your ping route, which is inside the Base class, you must create the respective trait like below-
This is the simple ping route of your project-
import akka.actor.ActorSystem
import akka.http.scaladsl.model.HttpResponse
import akka.http.scaladsl.model.StatusCodes._
import akka.http.scaladsl.server.Directives._
case class Base(system: ActorSystem) {
val routes = path(“ping”) {
get {
complete(HttpResponse(OK, entity = “pong”))
}
}
}
Below is the documentation of your ping route
import javax.ws.rs.Path
import akka.http.scaladsl.server.Route
import io.swagger.annotations._
@Path(“/ping”)
@Api(value = “/ping”)
@SwaggerDefinition(tags = Array(new Tag(name = “hello”, description = “operations useful for debugging”)))
trait Base {
@ApiOperation(value = “ping”, tags = Array(“ping”), httpMethod = “GET”, notes = “This route will return a output pong”)
@ApiResponses(Array(
new ApiResponse(code = 200, message = “OK”),
new ApiResponse(code = 500, message = “There was an internal server error.”)
))
def pingSwagger: Option[Route] = None
}
STEP-5
Add Swagger Routes with Other Routes and Bind the Routes to a Port to Start:
Below is an example of how you can combine swagger routes with your project routes.
object Boot {
def main(args: Array[String]): Unit = {
implicit val system = ActorSystem(“my-actor-system”)
implicit val materializer = ActorMaterializer()
implicit val executionContext = system.dispatcher
val routes = Base(system).routes ~ Swagger(system).routes ~
getFromResourceDirectory(“swagger-ui”)
val bindingFuture = Http().bindAndHandle(routes, “0.0.0.0”, 8080)
println(“App has started….”)
StdIn.readLine() // let it run until user presses return
bindingFuture
.flatMap(_.unbind()) // trigger unbinding from the port
.onComplete(_ => system.terminate()) // and shutdown when done
}
}
STEP-6
Start your application then open the below URL in your browser.
http://localhost:8080/swagger-ui/index.html
Conclusion:
This blog outlines the process of integrating Swagger UI using Akka HTTP. It explains how to set up Swagger UI, document routes using Swagger annotations, and combine these routes with your application’s routes. By following these steps, you can effectively incorporate interactive documentation for your application’s API endpoints.