hootsuite / sbt-swagger

Swagger SBT Plugin

SBT plugin for extracting Swagger & JAX-RS (jsr311) annotations from compiled classes into Swagger API models, which are then serialized to JSON for consumption with swagger-ui.

Installation

Modify the following 2 files in your project as described below:

• project/plugins.sbt
• project/Build.scala

project/plugins.sbt

Add sbt-swagger to your project's plugins:

addSbtPlugin("com.hootsuite" %% "sbt-swagger" % "1.0.0")

project/Build.scala

Configure your project's SBT build to use it. Make sure to replace com.example.your.project.package in the example below with your project's package prefix.

import com.hootsuite.sbt.swagger
val swaggerSettings = Seq(
  swagger.Sbt.apiVersion := "1.0",
  swagger.Sbt.basePath := "http://localhost",
  swagger.Sbt.apiPath := "/",
  //swagger.Sbt.packages := swagger.Sbt.All
  swagger.Sbt.packages := swagger.Sbt.WhitelistPrefixes(Seq("com.example.your.project.package")),
  swagger.Sbt.excludePropertyClassPrefixes := Set("play.api.libs.json")
) ++ com.hootsuite.sbt.swagger.Sbt.swaggerSettings
libraryDependencies ++= Seq(
  // API annotations
  "com.wordnik"          %  "swagger-annotations" % "1.3.10",
  // The following is only necessary if you're having trouble resolving dependencies
  "javax.ws.rs"          % "jsr311-api"           % "1.1.1")

// merge swaggerSettings into the project's settings
lazy val myProject = Project(
  id = "something-meaingful",
  base = file("."),
  settings = platformSettings ++
             dependencySettings ++
             swaggerSettings ++
             ...
)

Example

Check https://github.com/hootsuite/sbt-swagger/tree/master/sbt-swagger-example directory. This is a small complete sample application that uses sbt-swagger.

Usage

sbt swagger

Generates swagger JSON output in target/swagger/*.json files.

API Annotations

Swagger's @Api* annotations are the main markers and can be complemented with additional semantics with javax.ws.rs.* annotations. Neither Swagger nor JAX-RS alone offer a complete set of functionality.

This extractor favors Swagger's @Api* annotations over javax.ws.rs.* ones where there is an overlap: if a piece of information is specified using both Swagger @Api* and javax.ws.rs.* annotation, the generated models will use the information from Swagger's annotation.

// com.wordnik.swagger.annotations.*
// class level
@Api
@ApiModel
// method level
@ApiOperation
@ApiResponses
@ApiResponse
// parameter level
@ApiParam
@ApiModelProperty
// field level
@ApiModelProperty

// javax.ws.rs.*
// class level:
@Path
@Consumes
@Produces
// method level:
@GET
@POST
@HEAD
@PUT
@DELETE
@Path
@Consumes
@Produces
// parameter level:
@PathParam
@HeaderParam
@QueryParam
@FormParam
@CookieParam
@DefaultValue

Examples

See TweetEndpoints :

@Path("/tweet")
@Api(value = "/tweet", position = 2, description = "View a tweet, list tweets, or post a tweet. Everything about Tweets!")
@Produces(Array("text/plain"))
trait TweetEndpoints  {

  @GET // one operation to rule them all #annotations
  @Path("/get/{userId}")
  @ApiOperation(
    value = "Get a tweet of given tweetId",
    notes = "It actually returns a fixed value just for now.",
    position = 8, // relative to others in the generated output
    response = classOf[Tweet],
    responseContainer = "List")
  @Produces(Array("application/json"))
  @ApiResponses(value = Array(
    new ApiResponse(code = 403, message = "no tweets for you!"),
    new ApiResponse(code = 404, message = "invalid user id"),
    new ApiResponse(code = 405, message = "GETs only")
  ))
  def get( @PathParam("userId") userId: String,
           @HeaderParam("fromDate") fromDate: String,
           @QueryParam("toDate") toDate: String,
           @FormParam("what") what: String,
           @CookieParam("who") @DefaultValue("me") who: String
         ): Future[List[Tweet]] = {
    Future.successful(List(Tweet(123123, s"$userId", "an awesome message"), Tweet(79878999, s"$userId", "another one")))
  }
}

case class Tweet(id: Int, userId: String, body: String)

Known issues and workarounds

• Repeated invocations of the swagger command from the sbt console won't see updated/recompiled classes. Need to quit/reload sbt, or run sbt swagger from the shell each time. TODO: see issue #6 https://github.com/hootsuite/sbt-swagger/issues/6.

• All method parameters are automatically considered API parameters - no option to hide some that are not part of the API.

Workaround: extract a method that represents a 1:1 mapping with the actual exposed API in terms of parameters and input-output models, and wrap it as necessary for pre- (validation, etc) and post-processing.

• Map data types are not supported by the extractor.

Workaround: use List/Seq (and case classes).

• Options are supported in models (in most cases), but not as API parameters.

Workaround: perform validation outside of the designated API method, pass non-optional values to the API (and annotate with @ApiParam(required = true|false) when necessary).

• By default API parameters (all except path params) and model fields are considered optional. This should be made configurable by the plugin to allow projects to minimize the amount of required = true|false explicit annotations.

Workaround: use explicit annotations:

// for API parameters
@ApiParam(required = true)
// for model fields
@ApiModelProperty(required = true)
// for case class fields
@(ApiModelProperty @scala.annotation.meta.field)(required = true)

• Data type of API parameters and model fields is not extracted correctly for some combinations.

Workaround: use @ApiModelProperty(dataType = "...") to explicitly set it for the extractor. @ApiModelProperty works and is picked up from annotated API params as well, not just model properties.

// "list", "set" and "array" all map to the same "array[T]" in the generated apidocs JSON
// List container ignored for API parameters (but not for model properties)
@ApiModelProperty(dataType = "list[CreatePostRequest]")
postRequests: List[CreatePostRequest]

// extracted as Object otherwise
@(ApiModelProperty @field)(dataType = "set[integer]")
errors: Option[Set[Int]] = None
@(ApiModelProperty @field)(dataType = "integer")
minAge: Option[Int] = None,

• Enum values need to be explicitly set (compiler enforces that annotation values are constants).

@(ApiModelProperty @field)(allowableValues = "Public,DirectConnections,DirectAndSecondaryConnections", dataType = "enum")
globalRestriction: Option[GlobalRestriction.Value] = None,

Swagger API annotations quirks

(why we need to compensate with javax.ws.rs)

@ApiOperation :
  - does not allow to specify a (sub)path - would require one class per endpoint-path
  - javax.ws.rs.@Path does, can annotate methods

@ApiParam :
  - does not allow to specify the source of a parameter (header/path/query/form/cookie)
  - allows a few extra attributes to be specified:
    - required         (defaults to false)
    - dataType         useful when extractor didn't figure it out
    - allowMultiple    (defaults to false - except for path parameters)
    - allowableValues  useful for enum types (defaults to "")
    - description

@ApiModel :
 - marks explicitly a class as a model
   (though all models should be recursively discovered from API inputs/outputs)

@ApiModelProperty :
 - marks explicitly a method or field as a model property
 - 'hidden = true' useful for hiding implicits (e.g. JSON formatters)
   that are not part of the API and should be filtered out by the extractor

Contributing

Submit a bug report and pull request in GitHub.

Maintainers

• Tatsuhiro Ujihisa @ujm
• Johnny Bufu
• Diego Alvarez @d1egoaz
• Andres Rama @andres_rama_hs
• Steve Song @ssongvan