bhanditz / swagger-scala

swagger-scala

This implementation of swagger used to live in scalatra, it got extracted so it could be shared by more than one project.

How to use?

The main implementation of a swagger integration requires an implementation of com.wordnik.SwaggerEngine

Here is the implementation of that class for the default scalatra implementation

trait ScalatraSwaggerEngine[A <: SwaggerApi[_]] extends SwaggerEngine[A] {
  
  /**
   * Registers the documentation for an API with the given path.
   */
  def register(listingPath: String, resourcePath: String, description: Option[String], s: SwaggerSupportSyntax with SwaggerSupportBase, consumes: List[String], produces: List[String], protocols: List[String], authorizations: List[String])

}

/**
 * An instance of this class is used to hold the API documentation.
 */
class MySwagger(val apiVersion: String, val apiInfo: ApiInfo) extends ScalatraSwaggerEngine[Api] {
  
  val swaggerVersion = com.wordnik.swagger.Swagger.SpecVersion
  
  private[this] val logger = Logger[this.type]

  /**
   * Registers the documentation for an API with the given path.
   */
  def register(listingPath: String, resourcePath: String, description: Option[String], s: SwaggerSupportSyntax with SwaggerSupportBase, consumes: List[String], produces: List[String], protocols: List[String], authorizations: List[String]) = {
    logger.debug(s"registering swagger api with: { listingPath: $listingPath, resourcePath: $resourcePath, description: $resourcePath, servlet: ${s.getClass} }")
    val endpoints: List[Endpoint] = s.endpoints(resourcePath) collect { case m: Endpoint => m }
    _docs += listingPath -> Api(
      apiVersion,
      swaggerVersion,
      resourcePath,
      description,
      (produces ::: endpoints.flatMap(_.operations.flatMap(_.produces))).distinct,
      (consumes ::: endpoints.flatMap(_.operations.flatMap(_.consumes))).distinct,
      (protocols ::: endpoints.flatMap(_.operations.flatMap(_.protocols))).distinct,
      endpoints,
      s.models.toMap,
      (authorizations ::: endpoints.flatMap(_.operations.flatMap(_.authorizations))).distinct,
      0)
  }
}

This allows you to build the meta data necessary to generate a swagger api description. When you do generate the json as api description you should make use of the json formats provided in com.wordnik.swagger.SwaggerSerializers.defaultFormats

For example to render the index json you can use this method:

implicit formats: SwaggerFormats  = com.wordnik.swagger.SwaggerSerializers.defaultFormats
val mySwagger = new MySwagger(apiVersion, apiInfo)
Swagger.renderIndex(mySwagger, path => "/" + path)

And to render the description of a single doc you can use this:

implicit formats: SwaggerFormats  = com.wordnik.swagger.SwaggerSerializers.defaultFormats
val mySwagger = new MySwagger(apiVersion, apiInfo)
mySwagger.doc("/users").fold(JNothing)(Swagger.renderDoc(mySwagger, _, "/"))