本文详细介绍了如何使用Play框架和Swagger UI升级RESTful项目，包括安装激活器版本、配置版本信息、引入测试框架和依赖，以及准备Swagger UI文件。通过将项目与Apache HTTP服务器集成，实现API文档的可视化展示。最后，展示了如何在项目中添加注释，整合Swagger API，并部署应用。重点涵盖了从项目准备到部署的全流程。
Playframework and Swagger
1. Prepare the RESTful Project(Upgrade)
Download the latest activator version and place in the working directory.
https://www.playframework.com/documentation/2.4.3/ScalaTestingWithScalaTest
Some Changes to Upgrade the Version
activator
declare -r app_version=“1.3.6"
activator.bat
set APP_VERSION=1.3.6
build.sbt
import play.sb.PlayScala
…snip...
scalaVersion := "2.10.4"
ivyScala := ivyScala.value map { _.copy(overrideScalaVersion = true) }
libraryDependencies ++= Seq(
"org.scalatest" %% "scalatest" % "2.2.5" % "test",
"org.scalatestplus" %% "play" % "1.4.0-M4" % "test"
)
…snip...
project/build.properties
sbt.version=0.13.8
project/plugins.sbt
logLevel := Level.Warn
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.0")
addSbtPlugin("com.github.mpeltonen" % "sbt-idea" % "1.6.0")
resolvers += "Typesafe repository" at "https://repo.typesafe.com/typesafe/releases/"
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.4.3")
test/controllers/BookControllerSpec.scala
package controllers
import play.api.libs.json.JsValue
import scala.concurrent.Future
import org.scalatestplus.play._
import play.api.mvc._
import play.api.test._
import play.api.test.Helpers._
class BookControllerSpec extends PlaySpec with Results{
class TestController() extends Controller with BookController
"Book API#listBooks" should {
"size should be 2" in {
val controller = new TestController
val result: Future[Result] = controller.listBooks.apply(FakeRequest())
val bodyText: JsValue = contentAsJson(result)
bodyText must not be null
}
}
}
2. Prepare Swagger
Play with swagger-ui Project
> git clone https://github.com/swagger-api/swagger-ui.git
> npm install
> gulp
After that, we should see the distribution under the list folder.
Check if I have apache http server on my machine.
> apachectl -V
Server version: Apache/2.4.16 (Unix)
Server built: Jul 22 2015 21:03:09
Server's Module Magic Number: 20120211:47
Server loaded: APR 1.4.8, APR-UTIL 1.5.2
Compiled using: APR 1.4.8, APR-UTIL 1.5.2
Architecture: 64-bit
Server MPM: prefork
threaded: no
forked: yes (variable process count)
Server compiled with....
-D APR_HAS_SENDFILE
-D APR_HAS_MMAP
-D APR_HAVE_IPV6 (IPv4-mapped addresses enabled)
-D APR_USE_FLOCK_SERIALIZE
-D APR_USE_PTHREAD_SERIALIZE
-D SINGLE_LISTEN_UNSERIALIZED_ACCEPT
-D APR_HAS_OTHER_CHILD
-D AP_HAVE_RELIABLE_PIPED_LOGS
-D DYNAMIC_MODULE_LIMIT=256
-D HTTPD_ROOT="/usr"
-D SUEXEC_BIN="/usr/bin/suexec"
-D DEFAULT_PIDLOG="/private/var/run/httpd.pid"
-D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
-D DEFAULT_ERRORLOG="logs/error_log"
-D AP_TYPES_CONFIG_FILE="/private/etc/apache2/mime.types"
-D SERVER_CONFIG_FILE="/private/etc/apache2/httpd.conf"
Start the Server
> sudo apachectl start
Check the configuration
>cat /etc/apache2/httpd.conf
DocumentRoot "/Library/WebServer/Documents"
Copy the swagger-ui directory there
> sudo cp -r /Users/carl/book/swagger/swagger-ui/dist/* /Library/WebServer/Documents/
Visit swagger-ui
http://localhost/
Put http://localhost:8000/api-docs as parameter in the input box, we will have the api doc.
Or
http://localhost/index.html?url=http://localhost:8000/api-docs
Or
http://localhost:8000/assets/lib/swagger-ui/index.html?/url=http://localhost:8000/api-docs
3. Add notation in the Project
Some Sample codes are in sillycat-scalarest project version-1.3.6-swagger branch.
build.sbt
import play.sbt.PlayScala
name := """sillycat-scalarest"""
version := "1.0"
lazy val root = project.in(file(".")).enablePlugins(PlayScala)
scalaVersion := "2.10.4"
ivyScala := ivyScala.value map { _.copy(overrideScalaVersion = true) }
libraryDependencies ++= Seq(
"pl.matisoft" %% "swagger-play24" % "1.4",
//for internal swagger-ui
//"org.reflections" % "reflections" % "0.9.9" notTransitive(),
//"org.webjars" % "swagger-ui" % "2.1.8-M1",
"org.scalatest" %% "scalatest" % "2.2.5" % "test",
"org.scalatestplus" %% "play" % "1.4.0-M4" % "test"
)
fork in run := false
conf/routes
# Routes
# This file defines all application routes (Higher priority routes first)
# ~~~~
# Map static resources from the /public folder to the /assets URL path
GET /assets/*file controllers.Assets.versioned(path="/public", file)
# API Routes
GET /ping controllers.PingPongController.ping()
GET /api/v1/book controllers.BookController.listBooks
POST /api/v1/book controllers.BookController.saveBook
GET /api/v1/book/:id controllers.BookController.getBook(id:String)
PUT /api/v1/book/:id controllers.BookController.updateBook(id:String)
DELETE /api/v1/book/:id controllers.BookController.deleteBook(id:String)
# Swagger API
GET /api-docs @pl.matisoft.swagger.ApiHelpController.getResources
GET /api-docs/api/v1 @pl.matisoft.swagger.ApiHelpController.getResource(path = "/api/v1")
app/controllers/PingPongController.scala
package controllers
import play.api.mvc.{Action, Controller}
import com.wordnik.swagger.annotations.{Api,ApiModel,ApiModelProperty,ApiOperation,ApiParam,ApiResponse,ApiResponses}
@Api(value = "/api/v1", description = "Operations with Classifier")
object PingPongController extends Controller{
@ApiOperation(value = "Pings",
notes = "Returns pong",
response = classOf[String],
httpMethod = "GET",
produces = "text",
position = 1)
@ApiResponses(Array(
new ApiResponse(code = 200, message = "Successful ping", response = classOf[String])
)
)
def ping = Action {
Ok("pong")
}
}
Error Message
XMLHttpRequest cannot load http://localhost:8000/string. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost' is therefore not allowed access. The response had HTTP status code 404.
Solution:
http://enable-cors.org/server.html
https://www.playframework.com/documentation/2.4.3/CorsFilter
Filter Class app/Filters.scala
import javax.inject.Inject
import play.api.http.HttpFilters
import play.filters.cors.CORSFilter
class Filters @Inject() (corsFilter: CORSFilter) extends HttpFilters {
def filters = Seq(corsFilter)
}
Configuration in conf/application.conf
play.filters.cors {
#pathPrefixes = ["/some/path", ...]
allowedOrigins = ["http://localhost", "http://sillycat.ddns.net"]
allowedHttpMethods = ["GET", "POST", "PUT"]
#allowedHttpHeaders = ["Accept"]
#preflightMaxAge = 3 days
}
4. Playframework Deployment
Build the binary
> sbt dist
Run the binary
> bin/sillycat-scalarest -Dconfig.file=conf/application.conf -Dhttp.port=8000 -Dhttp.address=0.0.0.0
Need to use the same ui version
> git checkout tags/v2.1.8-M1
References:
Playframework
http://sillycat.iteye.com/blog/2241901
http://sillycat.iteye.com/blog/2242284
Swagger
https://github.com/matiwinnetou/swagger-play24
http://swagger.io/getting-started/
https://github.com/swagger-api/swagger-ui
1. Prepare the RESTful Project(Upgrade)
Download the latest activator version and place in the working directory.
https://www.playframework.com/documentation/2.4.3/ScalaTestingWithScalaTest
Some Changes to Upgrade the Version
activator
declare -r app_version=“1.3.6"
activator.bat
set APP_VERSION=1.3.6
build.sbt
import play.sb.PlayScala
…snip...
scalaVersion := "2.10.4"
ivyScala := ivyScala.value map { _.copy(overrideScalaVersion = true) }
libraryDependencies ++= Seq(
"org.scalatest" %% "scalatest" % "2.2.5" % "test",
"org.scalatestplus" %% "play" % "1.4.0-M4" % "test"
)
…snip...
project/build.properties
sbt.version=0.13.8
project/plugins.sbt
logLevel := Level.Warn
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.0")
addSbtPlugin("com.github.mpeltonen" % "sbt-idea" % "1.6.0")
resolvers += "Typesafe repository" at "https://repo.typesafe.com/typesafe/releases/"
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.4.3")
test/controllers/BookControllerSpec.scala
package controllers
import play.api.libs.json.JsValue
import scala.concurrent.Future
import org.scalatestplus.play._
import play.api.mvc._
import play.api.test._
import play.api.test.Helpers._
class BookControllerSpec extends PlaySpec with Results{
class TestController() extends Controller with BookController
"Book API#listBooks" should {
"size should be 2" in {
val controller = new TestController
val result: Future[Result] = controller.listBooks.apply(FakeRequest())
val bodyText: JsValue = contentAsJson(result)
bodyText must not be null
}
}
}
2. Prepare Swagger
Play with swagger-ui Project
> git clone https://github.com/swagger-api/swagger-ui.git
> npm install
> gulp
After that, we should see the distribution under the list folder.
Check if I have apache http server on my machine.
> apachectl -V
Server version: Apache/2.4.16 (Unix)
Server built: Jul 22 2015 21:03:09
Server's Module Magic Number: 20120211:47
Server loaded: APR 1.4.8, APR-UTIL 1.5.2
Compiled using: APR 1.4.8, APR-UTIL 1.5.2
Architecture: 64-bit
Server MPM: prefork
threaded: no
forked: yes (variable process count)
Server compiled with....
-D APR_HAS_SENDFILE
-D APR_HAS_MMAP
-D APR_HAVE_IPV6 (IPv4-mapped addresses enabled)
-D APR_USE_FLOCK_SERIALIZE
-D APR_USE_PTHREAD_SERIALIZE
-D SINGLE_LISTEN_UNSERIALIZED_ACCEPT
-D APR_HAS_OTHER_CHILD
-D AP_HAVE_RELIABLE_PIPED_LOGS
-D DYNAMIC_MODULE_LIMIT=256
-D HTTPD_ROOT="/usr"
-D SUEXEC_BIN="/usr/bin/suexec"
-D DEFAULT_PIDLOG="/private/var/run/httpd.pid"
-D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
-D DEFAULT_ERRORLOG="logs/error_log"
-D AP_TYPES_CONFIG_FILE="/private/etc/apache2/mime.types"
-D SERVER_CONFIG_FILE="/private/etc/apache2/httpd.conf"
Start the Server
> sudo apachectl start
Check the configuration
>cat /etc/apache2/httpd.conf
DocumentRoot "/Library/WebServer/Documents"
Copy the swagger-ui directory there
> sudo cp -r /Users/carl/book/swagger/swagger-ui/dist/* /Library/WebServer/Documents/
Visit swagger-ui
http://localhost/
Put http://localhost:8000/api-docs as parameter in the input box, we will have the api doc.
Or
http://localhost/index.html?url=http://localhost:8000/api-docs
Or
http://localhost:8000/assets/lib/swagger-ui/index.html?/url=http://localhost:8000/api-docs
3. Add notation in the Project
Some Sample codes are in sillycat-scalarest project version-1.3.6-swagger branch.
build.sbt
import play.sbt.PlayScala
name := """sillycat-scalarest"""
version := "1.0"
lazy val root = project.in(file(".")).enablePlugins(PlayScala)
scalaVersion := "2.10.4"
ivyScala := ivyScala.value map { _.copy(overrideScalaVersion = true) }
libraryDependencies ++= Seq(
"pl.matisoft" %% "swagger-play24" % "1.4",
//for internal swagger-ui
//"org.reflections" % "reflections" % "0.9.9" notTransitive(),
//"org.webjars" % "swagger-ui" % "2.1.8-M1",
"org.scalatest" %% "scalatest" % "2.2.5" % "test",
"org.scalatestplus" %% "play" % "1.4.0-M4" % "test"
)
fork in run := false
conf/routes
# Routes
# This file defines all application routes (Higher priority routes first)
# ~~~~
# Map static resources from the /public folder to the /assets URL path
GET /assets/*file controllers.Assets.versioned(path="/public", file)
# API Routes
GET /ping controllers.PingPongController.ping()
GET /api/v1/book controllers.BookController.listBooks
POST /api/v1/book controllers.BookController.saveBook
GET /api/v1/book/:id controllers.BookController.getBook(id:String)
PUT /api/v1/book/:id controllers.BookController.updateBook(id:String)
DELETE /api/v1/book/:id controllers.BookController.deleteBook(id:String)
# Swagger API
GET /api-docs @pl.matisoft.swagger.ApiHelpController.getResources
GET /api-docs/api/v1 @pl.matisoft.swagger.ApiHelpController.getResource(path = "/api/v1")
app/controllers/PingPongController.scala
package controllers
import play.api.mvc.{Action, Controller}
import com.wordnik.swagger.annotations.{Api,ApiModel,ApiModelProperty,ApiOperation,ApiParam,ApiResponse,ApiResponses}
@Api(value = "/api/v1", description = "Operations with Classifier")
object PingPongController extends Controller{
@ApiOperation(value = "Pings",
notes = "Returns pong",
response = classOf[String],
httpMethod = "GET",
produces = "text",
position = 1)
@ApiResponses(Array(
new ApiResponse(code = 200, message = "Successful ping", response = classOf[String])
)
)
def ping = Action {
Ok("pong")
}
}
Error Message
XMLHttpRequest cannot load http://localhost:8000/string. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost' is therefore not allowed access. The response had HTTP status code 404.
Solution:
http://enable-cors.org/server.html
https://www.playframework.com/documentation/2.4.3/CorsFilter
Filter Class app/Filters.scala
import javax.inject.Inject
import play.api.http.HttpFilters
import play.filters.cors.CORSFilter
class Filters @Inject() (corsFilter: CORSFilter) extends HttpFilters {
def filters = Seq(corsFilter)
}
Configuration in conf/application.conf
play.filters.cors {
#pathPrefixes = ["/some/path", ...]
allowedOrigins = ["http://localhost", "http://sillycat.ddns.net"]
allowedHttpMethods = ["GET", "POST", "PUT"]
#allowedHttpHeaders = ["Accept"]
#preflightMaxAge = 3 days
}
4. Playframework Deployment
Build the binary
> sbt dist
Run the binary
> bin/sillycat-scalarest -Dconfig.file=conf/application.conf -Dhttp.port=8000 -Dhttp.address=0.0.0.0
Need to use the same ui version
> git checkout tags/v2.1.8-M1
References:
Playframework
http://sillycat.iteye.com/blog/2241901
http://sillycat.iteye.com/blog/2242284
Swagger
https://github.com/matiwinnetou/swagger-play24
http://swagger.io/getting-started/
https://github.com/swagger-api/swagger-ui
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
