This is a module to support the play2 framework from playframework. It is written in scala but can be used with either java or scala-based play2 applications.
The play2 module is currently not available in a maven repo or the playframework modules. To use it, you'll have to build it from source, which is done by following these steps:
cd modules/swagger-play2
sbt play
publish-local
That will put the swagger-play2 module in your local ivy repository for use in your play2 application. Now you just need to include it in your application like this:
val appDependencies: Seq[sbt.ModuleID] = Seq("com.wordnik" %% "swagger-play2" % "1.1-SNAPSHOT")
You can then add swagger support to your app.
There are just a couple steps to integrate your Play2 app with swagger.
- Add the resource listing to your routes file (you can read more about the resource listing here
GET /resources.json controllers.ApiHelpController.getResources
- Annotate your REST endpoints with Swagger annotations. This allows the Swagger framework to create the api-declaration automatically!
In your controller for, say your "pet" resource:
@Path("/{id}")
@ApiOperation(value = "Find pet by ID", notes = "Returns a pet when ID < 10. " +
"ID > 10 or nonintegers will simulate API error conditions", responseClass = "Pet", httpMethod = "GET")
@ApiParamsImplicit(Array(
new ApiParamImplicit(name = "id", value = "ID of pet that needs to be fetched", required = true, dataType = "String", paramType = "path",
allowableValues = "range[0,10]")))
@ApiErrors(Array(
new ApiError(code = 400, reason = "Invalid ID supplied"),
new ApiError(code = 404, reason = "Pet not found")))
def getPetById(id: String) = Action { implicit request =>
petData.getPetbyId(getLong(0, 100000, 0, id)) match {
case Some(pet) => JsonResponse(pet)
case _ => JsonResponse(new value.ApiResponse(404, "Pet not found"), 404)
}
}
What this does is the following:
-
Tells swagger that this API listens to
/{id} -
Describes the operation as a
GETwith the documentationFind pet by Idwith more detailed notesReturns a pet .... -
Takes the "implicit" param
id, which is a datatypeStringand apathparam, andallowableValuesas a number between 0 and 10 -
Returns error codes 400 and 404, with the messages provided
In the routes file, you then wire this api as follows:
GET /pet.json controllers.ApiHelpController.getResource(path = "/pet")
GET /pet.json/:id controllers.PetApiController.getPetById(id)
This will "attach" the /pet.json api to the swagger resource listing, and the method to the getPetById method above
Swagger for play has two types of ApiParams--they are ApiParam and ApiParamImplicit. The distinction is that some
paramaters (variables) are passed to the method implicitly by the framework. ALL body parameters need to be described
with ApiParamImplicit annotations. If they are queryParams or pathParams, you can use ApiParam annotations.
Please take a look here for a full sample application using the Swagger Play2 module.