This project is no longer supported.
This branch (master) holds the latest version (major version 2.x) for latest play version supported (2.7); branch play-2.6 holds the swagger-play version for play 2.6 version (major.minor version 1.6.x).
Older versions are available though not anymore supported in the archive branch.
This is a module to support Swagger annotations within Play Framework controllers. It is based on the library https://github.com/swagger-api/swagger-play with several improvements. This library uses Swagger 1.5 and Play 2.7. It can be used for both Scala and Java based applications.
We also would like to support Swagger 2.0 in the future and contributions to that end will be gladly accepted.
- Minimal dependencies: only depends on the core Play module, so it won't bring unnecessary dependencies on the Akka HTTP server or anything else from Play.
SwaggerPluginno longer depends on onApplication.- Correct
Content-Lengthgeneration for JSON (originally proposed in #176) - No longer uses deprecated Play configuration methods (proposed in #162). Also uses
reference.conffor default values. - Clarifies compile-time DI docs (proposed in #157)
- Handle route delegation properly (#132 updated for Play 2.6)
- Add support for
dataTypeClassinApiImplicitParam(#174) - Add support for API keys (#117)
- Add support for OAuth2 (#183)
You can depend on pre-built libraries in maven central by adding the following dependency:
libraryDependencies ++= Seq(
"io.swagger" %% "swagger-play2" % "2.0.1-SNAPSHOT"
)
Or you can build from source.
sbt publishLocal
There are just a couple steps to integrate your Play2 app with swagger.
1. Add the Swagger module to your application.conf
play.modules.enabled += "play.modules.swagger.SwaggerModule"
2. Add the resource listing to your routes file (you can read more about the resource listing here)
GET /swagger.json controllers.ApiHelpController.getResources
3. 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:
@ApiResponses(Array(
new ApiResponse(code = 400, message = "Invalid ID supplied"),
new ApiResponse(code = 404, message = "Pet not found")))
def getPetById(
@ApiParam(value = "ID of the pet to fetch") 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 the methods in this controller should be described under the
/api-docs/petpath -
The Routes file 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 param
id, which is a datatypestringand apathparam -
Returns error codes 400 and 404, with the messages provided
In the routes file, you then wire this api as follows:
GET /pet/:id controllers.PetApiController.getPetById(id)
This will "attach" the /api-docs/pet api to the swagger resource listing, and the method to the getPetById method above
Please note that the minimum configuration needed to have a route/controller be exposed in swagger declaration is to have an Api annotation at class level.
Swagger for play has two types of ApiParams--they are ApiParam and ApiImplicitParam. The distinction is that some
paramaters (variables) are passed to the method implicitly by the framework. ALL body parameters need to be described
with ApiImplicitParam annotations. If they are queryParams or pathParams, you can use ApiParam annotations.
api.version (String) - version of API | default: "beta"
swagger.api.basepath (String) - base url | default: "http://localhost:9000"
swagger.filter (String) - classname of swagger filter | default: empty
swagger.api.info = {
contact : (String) - Contact Information | default : empty,
description : (String) - Description | default : empty,
title : (String) - Title | default : empty,
termsOfService : (String) - Terms Of Service | default : empty,
license : (String) - Terms Of Service | default : empty,
licenseUrl : (String) - Terms Of Service | default : empty
}
This plugin works by default if your application uses Runtime dependency injection.
Nevertheless, the plugin can be initialized using compile time dependency injection. For example, you can add the following to your class that extends BuiltInComponentsFromContext:
// This needs to be eagerly instantiated because this sets global state for swagger
val swaggerPlugin = new SwaggerPluginImpl(environment, configuration)
lazy val apiHelpController = new ApiHelpController(controllerComponents, swaggerPlugin)
Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent