Play Framework 2.5.x集成Swagger UI报错求助

Hey there! Let’s troubleshoot your Swagger integration issue with Play Framework 2.5.x. Since you’ve already added dependencies and configured routes but hit errors accessing swagger.json, here are the key steps to check and missing configurations you might need:

Play 2.5.x is an older release, so you need to use a swagger-play2 version explicitly built for it—typically the 1.5.x series. Double-check your build.sbt for the correct dependency (match it to your project’s Scala version, e.g., 2.11 or 2.12):

libraryDependencies += "io.swagger" %% "swagger-play2" % "1.5.18"

Avoid newer 2.x+ versions of swagger-play2, as they’re designed for newer Play releases and will cause compatibility breaks.

Play 2.5.x uses Guice for dependency injection, so you must enable the Swagger module in conf/application.conf:

play.modules.enabled += "play.modules.swagger.SwaggerModule"

Also add basic Swagger metadata here to prevent generation errors:

swagger.api.basepath = "http://localhost:9000" # Match your app's base URL
swagger.api.info.title = "Your API Name"
swagger.api.info.description = "Documentation for your service's endpoints"
swagger.api.info.version = "1.0"

Swagger generates swagger.json by scanning annotations on your controllers and models—missing these will cause the spec generation to fail:

• On your controller class (Java example):

  @Api(value = "/users", description = "Operations for managing user accounts")
  public class UserController extends Controller {
      // Controller logic
  }
  

  (For Scala controllers, use the Scala-compatible annotations from io.swagger.annotations)
• On individual API methods:

  @ApiOperation(
      value = "Fetch a user by ID",
      notes = "Returns a full user object if the ID exists in the system",
      response = User.class
  )
  public Result getUser(Long id) {
      // Method logic
  }
  

• On model classes (e.g., User):

  @ApiModel(value = "User", description = "Details of a user account")
  public class User {
      @ApiModelProperty(value = "Unique user identifier", required = true)
      private Long id;
      // Getters and setters
  }
  

Without these annotations, Swagger has no data to build the JSON spec.

Double-check your conf/routes entries to ensure they point to the correct Swagger-provided controllers:

# Serve the Swagger JSON specification
GET     /swagger.json           controllers.ApiHelpController.getResources
# Serve Swagger UI static files
GET     /swagger-ui/*file       controllers.Assets.at(path="/public/lib/swagger-ui", file)

Note: ApiHelpController is part of the swagger-play2 library—don’t try to implement it yourself.

When you hit an error accessing swagger.json, look at Play’s console logs or logs/application.log—the error message will pinpoint the issue:

• Guice injection errors mean the Swagger module isn’t enabled properly
• Annotation-related errors indicate a misconfigured controller/model annotation (e.g., missing required parameters)
• "Class not found" errors signal a mismatch between your dependency version and Play/Scala version

If swagger.json starts working but the Swagger UI page (/swagger-ui/index.html) returns a 404:

• For swagger-play2 1.5.x, you may need to manually add Swagger UI 2.x static files to your project’s public/lib/swagger-ui directory. Download the appropriate version, unzip it, and copy the files to this path.

Sometimes in Play’s dev mode, hot reloading skips annotation scanning. Try stopping and restarting the app to ensure all Swagger components load correctly.

内容的提问来源于stack exchange，提问作者joesan