ikhoon / finatra-swagger

Fork of Swagger Support For Finatra to support Scala 2.11 & 2.12

GitHub

finatra-swagger

CircleCI Codacy Badge

Add Swagger UI support to Finatra web framework.

Currently supports Scala 2.12 & 2.11 with Finatra 17.12.0

For older versions, see the original repository by xiaodongw

Getting started

The major and minor version of the library matches the Finatra major and minor version:

libraryDependencies += "com.github.ikhoon" %% "finatra-swagger" % "17.12.0"

First, create a subclass of a SwaggerModule

object SampleSwaggerModule extends SwaggerModule {

  @Singleton
  @Provides
  def swagger: Swagger = {
    val swagger = new Swagger()

    val info = new Info()
      .description("The Student / Course management API, this is a sample for swagger document generation")
      .version("1.0.1")
      .title("Student / Course Management API")

    swagger
      .info(info)
      .addSecurityDefinition("sampleBasic", {
        val d = new BasicAuthDefinition()
        d.setType("basic")
        d
      })

    swagger
  }
}

Then add the module to the list of modules in the Server. Don't forget to include the DocsController in the router!

object SampleApp extends HttpServer {
  override protected def modules = Seq(SampleSwaggerModule)

  override def configureHttp(router: HttpRouter) {
    router
      .add[DocsController]
      ...
  } 
}

Lastly, configure the endpoints using the SwaggerRouteDSL

class SampleController@Inject()(s: Swagger) extends SwaggerController {
  implicit protected val swagger = s

  getWithDoc("/students/:id") { o =>
    o.summary("Read the detail information about the student")
      .tag("Student")
      .routeParam[String]("id", "the student id")
      .responseWith[Student](200, "the student details")
      .responseWith(404, "the student is not found")
  } { request =>
    ...
  }

To see the Swagger UI, use the /docs endpoint. This can be overridden using the Finatra flag "swagger.docs.endpoint"

To see the model that is JSON document that is generated, use /swagger.json.

Features

TODO

To see these in action, check out the examples directory