swagger 界面_使用Swagger和Scalatra进行界面驱动的开发简介

swagger 界面

自从三年前开始使用以来，Scalatra网络微框架已经发展成为一个轻量级但功能齐全的模型-视图-控制器（MVC）框架，背后是一个活跃的社区。 Scalatra最初是Ruby流行的Sinatra DSL移植到Scala语言的开始。 从那时起，两个系统独立发展，而Scalatra获得了诸如Atmosphere 集成和Akka支持之类的功能。

BBC Future Media已将其用于Linked Data Writer API，以可扩展和可管理的方式管理大型数据集，并且gov.uk也已使用它 。

Scalatra最成功的事情之一就是API的构造。 在过去的几年中，REST API已成为Web的命脉。 Scalatra功能的相对较新的功能是与Swagger工具集的集成，该工具集由Wordnik的人员制作 。

昂首阔步是什么？

Swagger是一项规范，它使您可以使用JSON文档快速定义REST API的功能。 但这不只是规格。 它提供了交互式API文档的自动生成，多种语言的客户端代码生成以及Java和Scala中的服务器端代码生成。

尽管它们是该项目中最引人注目的组件，并且会给用户留下深刻印象，但是Swagger制作的文档对于在API设计阶段促进API生产者与消费者之间的交流也非常有用。

让我们来看看它们是如何工作的。 我们将使用Scalatra构建一个小的REST API，然后使用Swagger记录我们的路线。

您需要做的第一件事是安装Scalatra。 最简单的方法是按照Scalatra网站上的安装说明进行操作 。 如果使用那些IDE，请参阅底部的注释以设置Eclipse或IntelliJ，但是您应该可以在任何文本编辑器中进行本教程。

一旦安装了JVM以及cs ， giter8和sbt ，您就可以生成一个新的Scalatra项目。

入门

在命令行中输入：

g8 scalatra/scalatra-sbt --branch develop

系统将询问您有关项目的一系列问题。 这样回答：

organization [com.example]:
package [com.example.app]: com.example.swagger.sample
name [scalatra-sbt-prototype]: flowershop
servlet_name [MyScalatraServlet]: FlowersController
scala_version [2.9.2]:
version [0.1.0-SNAPSHOT]:

点击以接受组织，scala_version和版本问题的默认值。

回答完最后一个问题后，将生成一个完整的Scalatra项目。 让我们检查一下它是否有效。 将目录更改为flowershop文件夹，然后输入以下命令来运行Scala的简单构建工具 ：

cd flowershop
sbt

为此 ，您需要最新的sbt 0.12.1 。 sbt 0.12.0将起作用，只需将文件project/build.properties的版本号降级。

sbt将负责下载Scalatra的所有依赖项。 首次使用时，可能会花费几分钟，因为您将获得完整的Scala开发环境，嵌入式Web服务器（jetty），Scalatra本身以及几个配套库。

当sbt完成所有设置后，您应该可以通过在sbt提示符下键入以下内容（看起来像“>”）来启动应用程序。

container:start

这将在http：// localhost：8080上启动码头。 在浏览器中访问该URL，您应该会看到一个Hello World应用程序。

您不需要手动重新编译您的应用程序并在更改代码时重新启动Jetty，因此请在sbt提示符下键入以下内容：

~; copy-resources; aux-compile

这告诉sbt每当更改文件时就自动重新编译并重新加载应用程序。

因此，现在我们为花店提供了一个控制器。 让我们设置一个RESTful接口，使我们能够浏览花朵。

打开src/main/scala/com/example/swagger/sample找到的FlowersController.scala文件。 首先，您将看到一个非常简单的生成控制器。 在应用程序的根路径get("/")上安装了一个“ hello world”动作，可以使用HTTP GET到路径"/"来访问该动作。 它也有一种方法来处理404和Scalate模板，这是我们的API不需要的。

Scalatra允许您通过将Scala特征混合到类定义中来轻松地向控制器添加功能。 让我们通过删除ScalateSupport ，因为我们不需要对我们的APIHTML模板支持。 删除类定义的with ScalateSupport部分，因此如下所示：

class FlowersController extends ScalatraServlet {
  

您也可以删除import scalate.ScalateSupport ，它是不需要的。

您也可以删除notFound和get（“ /”）动作。 您将得到一个空的Scalatra控制器：

package com.example.swagger.sample

import org.scalatra._

class FlowersController extends ScalatraServlet {

}

在进行这些更改并保存文件时，请在终端中检查sbt的输出。 您应该看到源代码会自动重新编译自身并重新加载应用程序。 精简控制器后，终端输出将变为绿色。 现在，您已经从FlowersController中提取了所有路由，因此您将无法在浏览器中看到任何内容。

设置数据模型

让我们设置一些数据。 由于我们希望专注于学习Swagger，因此我们不会尝试在本教程中实际保留任何内容。 我们可以改用Scala案例类来模拟数据模型。 如果您想了解如何设置ScalaQuery和Scala ORM，请参阅SmartJava的 Jos Dirksen的教程。

首先，我们需要一个花朵模型。 在src/main/scala/com/example/swagger/sample添加一个新目录，并将其称为models 。 然后将以下代码放在新文件Models.scala中：

模型

package com.example.swagger.sample.models

// A Flower object to use as a faked-out data model
case class Flower (slug: String , name: String )

Scala case class自动向类定义中添加获取器和设置器，因此我们在这里获得了很多功能而没有很多样板。

让我们添加一些花朵数据。

通过在src/main/scala/com/example/swagger/sample内添加一个新的data目录来建立数据名称空间。 然后在该目录中添加一个新文件， FlowerData.scala 。

该文件的内容应如下所示：

FlowerData.scala

package com.example.swagger.sample.data

import com.example.swagger.sample.models ._

object FlowerData {

  /**    * Some fake flowers data so we can simulate retrievals.    */
  var all = List (
      Flower ( "yellow-tulip" , "Yellow Tulip" ),
      Flower ( "red-rose" , "Red Rose" ),
      Flower ( "