精华内容
下载资源
问答
  • swagger 界面 自从三年前开始使用以来,Scalatra网络微框架已经发展成为一个轻量级但功能齐全的模型-视图-控制器(MVC)框架,背后是一个活跃的社区。 Scalatra最初是Ruby流行的Sinatra DSL移植到Scala语言的开始。 ...

    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以及csgiter8sbt ,您就可以生成一个新的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 ( "black-rose" , "Black Rose" ))
    }
    

    这给了我们足够的数据处理能力,至少可以证明我们的API功能。

    让我们做一个新的控制器动作来检索花朵。 添加一些导入,以便通过在包定义之后的顶部添加以下内容来访问FlowersController类中的模型和数据:

    // Our models
    import com.example.swagger.sample.models._
    
    // Fake flowers data
    import com.example.swagger.sample.data._
    

    取花

    现在,让我们制作第一个API方法,Scalatra操作,使客户可以浏览花朵。 将其放入FlowersController类的主体中:

    get("/" ){
      FlowerData .all
    }
    
    

    它看起来并不多,但是通过调用我们刚刚定义的FlowerData对象的all方法,这对我们来说是一种虚假的数据检索。 这大致相当于在Java或C#中调用静态方法,在Ruby中调用类方法。

    如果在浏览器中查看http:// localhost:8080 / ,应该会看到以下结果:

    List(Flower(yellow-tulip,Yellow Tulip), Flower(red-rose,Red Rose), Flower(black-rose, Black Rose))

    Scalatra为我们找到了所有鲜花,并返回了数据。 不过,纵观目前为止,它不是一个描述性很强的API。 实际上正在检索什么资源? 通过查看URL不可能知道。 让我们改变一下。

    设置安装路径以提高API的清晰度

    每个Scalatra应用程序都有一个名为ScalatraBootstrap.scala的文件,位于src/main/scala目录中。 该文件允许您将控制器安装在所需的任何URL路径上。 如果您现在打开自己的,看起来会像这样:

    import com.example.swagger.sample._
    import org.scalatra._
    import javax.servlet.ServletContext
    
    class ScalatraBootstrap extends LifeCycle {
      override def init(context: ServletContext ) {
        context.mount( new FlowersController , "/*" )
      }
    }
    

    让我们对其进行一些更改,向FlowersController添加一个路由名称空间:

    import  com.example.swagger.sample._
    import org.scalatra._
    import javax.servlet.ServletContext
    
    class ScalatraBootstrap extends LifeCycle {
    
      override def init {
        context.mount( new FlowersController , "/flowers" )
      }
    }
    

    唯一的更改是将“ / *”安装点替换为“ / flowers”。 很简单。 让我们确保它起作用。 在浏览器中点击URL http:// localhost:8080 / flowers ,您应该再次看到与以前相同的结果:

    List(Flower(yellow-tulip,Yellow Tulip), Flower(red-rose,Red Rose), Flower(black-rose, Black Rose))

    这是更具描述性的URL路径。 客户现在可以了解他们正在使用flower资源。

    API操作的自动JSON输出

    仔细看看输出。 这里发生了什么? Scalatra已将FlowerData.all值转换为字符串,并以其Scala源表示形式作为响应。 这是默认的行为,但是实际上我们不希望事情以这种方式运行-我们想使用JSON作为数据交换格式。

    让我们开始工作。 Scalatra 2.2包含一些新的JSON处理功能,这使其变得轻而易举。

    为了使用Scalatra的JSON功能,我们需要添加几个库依赖项,以便我们的应用程序可以访问一些新代码。 在生成的项目的根目录中,您将找到一个名为build.sbt的文件。 打开它,然后在其他与scalatra相关的行之后,将以下两行添加到libraryDependencies序列中:

     "org.scalatra" % "scalatra-json" % "2.2.0-SNAPSHOT" ,
      "org.json4s" %% "json4s-jackson" % "3.0.0" ,
    

    build.sbt在某种程度上等效于Java中的maven pom.xml或Ruby中的Gemfile ,只要它可以跟踪项目的所有依赖项并可以为您下载它们即可。

    重新启动sbt以下载新的jar。 为此,您可以先按“ enter”键(停止自动重新编译),然后在sbt提示符下键入exit 。 然后再次键入sbt 。 您应该看到一些消息,告诉您sbt正在下载新的依赖项,然后您将回到提示窗口。 启动容器并再次重新编译:

    container:start
    ~; copy-resources; aux-compile

    将以下导入添加到FlowersController文件的顶部,以使新的JSON库可用:

    // JSON-related libraries
    import scala.collection.JavaConverters._
    import org.json4s.{DefaultFormats, Formats}
    
    // JSON handling support from Scalatra
    import org.scalatra.json._

    现在,我们可以向FlowersController添加一些魔术了。 将这行代码放在控制器类定义的下面,将允许您的控制器自动将Scalatra操作结果转换为JSON:

    // Sets up automatic case class to JSON output serialization, required by
      // the JValueResult trait.
      protected implicit val jsonFormats: Formats = DefaultFormats

    就像它的Sinatra前辈一样,Scalatra具有一组丰富的构造,用于在向控制器发出请求之前和之后运行事物。 在所有请求before运行before过滤器。 添加一个before过滤器以将此控制器的所有输出设置为将所有操作结果的内容类型设置为JSON:

     // Before every action runs, set the content type to be in JSON format.
      before() {
        contentType = formats( "json" )
      }
    

    现在将JacksonJsonSupportJValueResult混合到您的servlet中,以便您的控制器声明如下所示:

    class FlowersController extends ScalatraServlet with JacksonJsonSupport with JValueResult {

    此时,您的代码应再次编译。 在http:// localhost:8080 / flowers刷新浏览器,然后/操作的输出突然变为JSON:

    [{"slug" : "yellow-tulip" , "name" : "Yellow Tulip" },{ "slug" : "red-rose" , "name" : "Red Rose" },{ "slug" : "black-rose" , "name" : "Black Rose" }]
    

    我们混合到控制器中的JValueResultJsonJacksonSupport特性与implicit val jsonFormats组合在一起,现在将所有Scalatra操作结果值转换为JSON。

    使Flowers API可搜索

    接下来,让我们的API可搜索。 我们希望能够按名称搜索花朵并获取与查询匹配的结果列表。 最简单的方法是在控制器中的/内部进行一些模式匹配。

    目前,该路线如下所示:

    get("/" ){
        FlowerData .all
      }
    

    我们可以更改它以读取查询字符串参数,并在我们的鲜花列表中进行搜索。

    /*    * Retrieve a list of flowers    */
      get( "/" ){
        params.get( "name" ) match {
          case Some (name) => FlowerData .all filter (_.name.toLowerCase contains name.toLowerCase())
          case None => FlowerData .all
        }
      }
    

    现在,Scalatra可以从查询字符串中获取所有传入的?name=foo参数,并将其用作变量name ,然后对FlowerData列表进行过滤以匹配结果。

    如果在http:// localhost:8080 / flowers刷新浏览器,则应该看不到任何变化-所有花都返回了。 但是,如果将浏览器指向http:// localhost:8080 / flowers?name = rose ,则只会看到玫瑰。

    通过子弹取回一朵花

    目前,我们将创建的最后一个控制器方法是检索特定花朵的方法。 我们可以很容易地通过它的子弹检索花朵,如下所示:

    get("/:slug" ) {
        FlowerData .all find (_.slug == params( "slug" ))  match {
          case Some (b) =>b
          case None =>halt( 404 )
        }
      }
    

    再一次,我们使用Scala的模式匹配来查看是否可以找到匹配的子弹。 如果找不到所需的花朵,则该操作将返回404并暂停处理。

    您可以通过将浏览器指向一个段来查看API的输出,例如http:// localhost:8080 / flowers / yellow-tulip

    {"slug" : "yellow-tulip" , "name" : "Yellow Tulip" }
    

    令人高兴的是,由于我们的before()过滤器会在每个操作上运行,因此JSON格式转换器仍在我们的输出上运行。 我们无需任何努力即可获得自动JSON支持。 甜。

    使用Swagger进行界面驱动的开发

    至此,我们有了REST API的开始。 它定义了两个动作,并为API客户端提供了一种方法来查看我们的花店中有哪些花。 实现所需的功能后,我们可以在这里停止。 但是我们缺少两件事:人类可读的文档和客户端集成代码。 如果没有这些功能,API的实用性将大大降低。

    API是对机器进行数据交换的一种方式,但设计和建造的API的过程中也需要大量的之间的沟通。 当API的用户能够参与其中并详细说明他们的需求,并且API实施者将这些对话简化为适合所需用户故事或用例的界面时,就会发生最佳的API设计。 从历史上看,您需要使用cURL或阅读WSDL来了解API的功能这一事实严重限制了非技术人员参与API设计过程的能力。 仅建立连接的技术复杂性掩盖了一个事实,即从本质上讲,REST API固有的概念并不是特别难以理解。

    以一种引人入胜,易于理解的方式使API的方法,参数和响应可见,可以改变构建REST API的过程。 Wordnik (单词含义站点)的人们已经建立了一个名为Swagger的工具集,可以提供帮助。

    昂首阔步是一堆不同的东西。 它是一个文档,用于记录REST API的行为-API的名称,提供的资源,可用的方法及其参数以及返回值。 该规范可以独立使用,以使用简单的JSON文件描述您的API。

    Swagger资源文件

    如果需要,可以手动编写Swagger JSON描述文件。 我们的FlowersController的Swagger资源描述可能看起来像这样(不过,请不要打扰,因为稍后我们将看到如何自动执行此操作):

    {"basePath" : "http://localhost:8080" , "swaggerVersion" : "1.0" , "apiVersion" : "1" , "apis" :[{ "path" : "/api-docs/flowers.{format}" , "description" : "The flowershop API. It exposes operations for browing and searching lists of flowers" }]}
    

    该文件描述了我们提供的API。 每个API都有自己的JSON描述符文件,该文件详细说明了它提供的资源,这些资源的路径,必需和可选参数以及其他信息。

    样本Swagger资源文件

    我们的flower资源的描述符可能看起来像这样:

    {"resourcePath" : "/" , "listingPath" : "/api-docs/flowers" , "description" : "The flowershop API. It exposes operations for browing and searching lists of flowers" , "apis" :[{ "path" : "//" , "description" : "" , "secured" :true, "operations" :[{ "httpMethod" : "GET" , "responseClass" : "List[Flower]" , "summary" : "Show all flowers" , "notes" : "Shows all the flowers in the flower shop. You can search it too." , "deprecated" :false, "nickname" : "getFlowers" , "parameters" :[{ "name" : "name" , "description" : "A name to search for" , "required" :false, "paramType" : "query" , "allowMultiple" :false, "dataType" : "string" }], "errorResponses" :[]}]},{ "path" : "//{slug}" , "description" : "" , "secured" :true, "operations" :[{ "httpMethod" : "GET" , "responseClass" : "Flower" , "summary" : "Find by slug" , "notes" : "Returns the flower for the provided slug, if a matching flower exists." , "deprecated" :false, "nickname" : "findBySlug" , "parameters" :[{ "name" : "slug" , "description" : "Slug of flower that needs to be fetched" , "required" :true, "paramType" : "path" , "allowMultiple" :false, "dataType" : "string" }], "errorResponses" :[]}]}], "models" :{ "Flower" :{ "id" : "Flower" , "description" : "Flower" , "properties" :{ "name" :{ "description" :null, "enum" :[], "required" :true, "type" : "string" }, "slug" :{ "description" :null, "enum" :[], "required" :true, "type" : "string" }}}}, "basePath" : "http://localhost:8080" , "swaggerVersion" : "1.0" , "apiVersion" : "1" }
    

    然后可以将这些JSON文件提供给标准HTML / CSS / JavaScript客户端,以使人们可以轻松浏览文档。 令人印象深刻-花一点时间查看Swagger Pet Store示例。 单击路由定义以查看每种资源可用的操作。 您可以使用Web界面向API发送真实的测试查询,并查看API对每个查询的响应。

    Swagger语言和框架集成

    让我们回到规格文件。 除了像Pet Store示例中那样启用自动文档编制之外,这些JSON文件还允许自动以多种语言生成客户端和服务器代码。

    这意味着除非您愿意,否则无需手动生成这些JSON文件。 与各种框架进行了集成,包括ASP.NETexpressfubumvcJAX-RSPlayRubySpring MVC

    框架集成允许您注释RESTful API中的代码,以便自动生成有效的Swagger规范的JSON描述符。 这意味着,一旦您注释了API方法,便可以使用swagger-ui免费获得一些非常有用(非常漂亮)的文档功能。 您还可以使用swagger-codegen项目以多种语言生成客户端和服务器代码。 可以为Flash,Java,JavaScript,Objective-C,PHP,Python,Python3,Ruby或Scala生成客户端代码。

    使用Swagger设置Scalatra花店

    让我们用Swagger注释我们的Scalatra花店,以便自动生成可运行的API文档。

    添加依赖项

    首先,将Swagger依赖项添加到build.sbt文件中:

    "com.wordnik" % "swagger-core_2.9.1" % "1.1-SNAPSHOT" ,
    "org.scalatra" % "scalatra-swagger" % "2.2.0-SNAPSHOT" ,
    

    退出sbt控制台,然后再次在应用程序的顶级目录中键入sbt ,以获取依赖关系。 然后运行container:start~; copy-resources; aux-compile ~; copy-resources; aux-compile ~; copy-resources; aux-compile使代码重新加载再次进行。

    现在,您需要将Scalatra的Swagger支持导入到FlowersController中:

    // Swagger support
    import org.scalatra.swagger._
    

    自动生成resources.json规范文件

    任何使用Swagger支持的Scalatra应用程序都必须实现Swagger控制器。 毕竟,那些JSON规范文件(否则我们需要手工编写)需要提供某些东西。 让我们向我们的应用程序添加一个标准的Swagger控制器。 将此代码拖放到FlowersController.scala旁边的新文件中。 您可以将其称为FlowersSwagger.scala

    FlowersSwagger.scala

    package com.example.swagger.sample
    
    import org.scalatra.swagger .{ JacksonSwaggerBase , Swagger , SwaggerBase }
    
    import org.scalatra.ScalatraServlet
    import com.fasterxml.jackson.databind._
    import org.json4s.jackson.Json4sScalaModule
    import org.json4s. { DefaultFormats , Formats }
    
    class ResourcesApp ( implicit val swagger: Swagger ) extends ScalatraServlet with JacksonSwaggerBase
    
    class  FlowersSwagger extends Swagger ( "1.0" , "1" )
    

    该代码基本上为您提供了一个新的控制器,该控制器将为应用程序中的每个Swaggerized API方法自动生成Swagger兼容的JSON规范。

    但是,您的应用程序的其余部分尚不了解。 为了正确设置所有内容,您需要更改ScalatraBootstrap文件,以便容器知道此新servlet。 当前看起来像这样:

    import com.example.swagger.sample._
    import org.scalatra._
    import javax.servlet.ServletContext
    
    class ScalatraBootstrap extends LifeCycle {
      override def init(context: ServletContext ) {
        context.mount( new FlowersController , "/flowers" )
      }
    }
    
    

    将其更改为如下所示:

    class ScalatraBootstrap extends LifeCycle {
    
      implicit val swagger = new FlowersSwagger
    
      override def init(context: ServletContext ) {
        context mount( new FlowersController , "/flowers" )
        context mount ( new ResourcesApp , "/api-docs" )
      }
    }
    

    将SwaggerSupport添加到FlowersController

    然后,我们可以添加一些代码以在FlowersController上启用Swagger。 当前,您的FlowersController声明应如下所示:

    class FlowersController extends ScalatraServlet with JacksonJsonSupport with JValueResult {
    

    让我们添加SwaggerSupport特性,并使FlowerController在其构造函数中意识到swagger。

    class FlowersController ( implicit val swagger: Swagger ) extends ScalatraServlet with JacksonJsonSupport with JValueResult with SwaggerSupport {
    

    为了使我们的应用程序再次编译,我们需要在FlowersController中添加名称和描述。 这使Swagger可以告知客户我们的API的名称及其作用。 您可以通过将以下代码添加到FlowersController类的主体中来做到这一点:

    override protected val applicationName = Some ( "flowers" )
      protected val applicationDescription = "The flowershop API. It exposes operations for browsing and searching lists of flowers, and retrieving single flowers." 

    设置就差不多了。 现在,我们可以开始记录API的方法了。

    注释API方法

    Swagger注释在Scalatra中非常简单。 您使用一些信息来装饰每个路由,Scalatra会为您的路由生成JSON规范。

    让我们先执行get("/")路由。

    现在,它看起来像这样:

    get("/" ){
        params.get( "name" ) match {
          case Some (name) => FlowerData .all filter (_.name.toLowerCase contains name.toLowerCase)
          case  None => FlowerData .all
        }
      }
    

    我们需要向该方法中添加一些信息,以便告诉Swagger该方法的作用,可以采用的参数以及响应的方式。

    get("/" ,
        summary( "Show all flowers" ),
        nickname( "getFlowers" ),
        responseClass( "List[Flower]" ),
        parameters( Parameter ( "name" , "A name to search for" , DataType.String , paramType = ParamType.Query , required = false )),
        endpoint( "" ),
        notes( "Shows all the flowers in the flower shop. You can search it too." )){
        params.get( "name" )  match {
          case Some (name) => FlowerData .all filter (_.name.toLowerCase contains name.toLowerCase)
          case None => FlowerData .all
        }
      }
    

    让我们详细阅读注释。

    summarynotes应为人类可读的消息,您打算由API客户端开发人员阅读。 摘要是简短描述,而注释应提供更长的描述,并包括任何可能会被人遗漏的值得注意的功能。

    nickname旨在用作机器可读的密钥,客户端代码可使用该nickname来识别此API动作-例如,swagger-ui将使用该别名来生成方法名称。 您可以随心所欲地调用它,但要确保其中不包含任何空格,否则客户端代码生成可能会失败-因此“ getFlowers”或“ get_flowers”很好,而“ get flowers”则不行。

    responseClass本质上是一种类型注释,以便客户端知道期望返回的数据类型。 在这种情况下,客户应期望有一个Flower对象列表。

    parameters详细说明了可能传递给此路由的所有参数,以及是否应将其作为路径,post params或查询字符串参数的一部分。 在这种情况下,我们定义了一个名为name的可选查询字符串参数,该参数与我们的操作期望的参数匹配。

    最后, endpoint注释为此方法定义了任何特殊的参数替换或其他路由信息。 此特定路线非常简单,因此我们可以将其留空。

    我们可以对get(/:slug)路由执行相同的操作。 从此更改:

    get("/:slug" ) {
        FlowerData .all find (_.slug == params( "slug" )) match {
          case Some (b) =>b
          case None =>halt( 404 )
        }
      }
    

    对此:

    get("/:slug" ,
        summary( "Find by slug" ),
        nickname( "findBySlug" ),
        responseClass( "Flower" ),
        endpoint( "{slug}" ),
        notes( "Returns the flower for the provided slug, if a matching flower exists." ),
        parameters(
          Parameter ( "slug" , "Slug of flower that needs to be fetched" ,
            DataType.String ,
            paramType = ParamType.Path ))) {
        FlowerData .all find (_.slug == params( "slug" )) match {
          case Some (b) =>b
          case None =>halt( 404 )
        }
      }
    

    此处的Swagger注释与get("/")路由的注释大部分相似。 有几件事要注意。

    这次将endpoint定义为{slug} 。 大括号告诉Swagger,应将名为{slug}的路径参数的内容替换为任何生成的路由(请参见下面的示例)。 还要注意,这一次,我们定义了ParamType.Path ,因此我们将slug参数作为路径的一部分而不是查询字符串进行传递。 由于我们没有将slug参数设置为required = false ,就像我们在另一条路线中为name参数设置的那样,Swagger会假设需要使用Slug。

    现在,让我们看看我们获得了什么。

    在我们的应用程序中添加Swagger支持,并在FlowersController中添加Swagger注释,这意味着我们有了一些新功能。 在浏览器中检查以下URL:

    http:// localhost:8080 / api-docs / resources.json

    您应该会看到一个自动生成的可用API的Swagger描述(在这种情况下,只有一个,但是我们的应用程序可能定义了多个API,在此将它们全部注明):

    {"basePath" : "http://localhost:8080" , "swaggerVersion" : "1.0" , "apiVersion" : "1" , "apis" :[{ "path" : "/api-docs/flowers.{format}" , "description" : "The flowershop API. It exposes operations for browing and searching lists of flowers" }]}
    

    现在是美好的部分。

    使用swagger-ui浏览您的API

    如果浏览到http://petstore.swagger.wordnik.com/ ,则将看到默认的Swagger演示应用程序-Pet Store-并且将能够浏览其文档。 一件可能不会立即显而易见的事情是,我们也可以使用此应用程序浏览我们当地的花店。

    之所以显示Pet Store文档,是因为默认情况下将http://petstore.swagger.wordnik.com/api/resources.json输入URL字段。

    将您的Swagger资源描述符URL- http://localhost:8080/api-docs/resources.json粘贴到URL字段中,删除“特殊键”键,然后按“浏览”按钮。 您将获得对API文档的全面了解。 尝试单击“ GET / flowers”路由以展开其下方的操作,然后在“ name”参数的输入框中输入单词“ rose”。 对于我们之前定义的搜索方法,您将获得JSON输出的回报。

    另请注意,swagger-ui会响应输入验证:您必须输入/flowers/{slug}才能尝试/flowers/{slug}路由,因为我们已在Swagger批注中将其标记为必需参数。 请注意,当您输入“ yellow-tulip”之类的子弹时,此路由上的"{slug}"端点注释会导致swagger-ui将请求触发为/flowers/yellow-tulip

    如果您想托管自己的自定义文档版本,则当然可以从Github下载swagger-ui代码并将其拖放到任何HTTP服务器上。

    跨域安全性说明

    有趣的是,您可以使用位于http://petstore.swagger.wordnik.com的远程托管文档浏览器来浏览http:// localhost上的应用程序。 为什么会这样呢? JavaScript安全性限制不应该在这里发挥作用吗?

    它起作用的原因是Scalatra具有内置的跨域资源共享(CORS)支持,默认情况下允许所有请求域的跨域JavaScript请求。 这样可以轻松地为JS API客户端提供服务-但是,如果需要,您可以使用Scalatra的CorsSupport特性将请求锁定到特定域。 有关更多信息,请参见Scalatra Helpers文档。

    结论

    现在,您无需花费很多样板代码,就可以构造一个简单的REST API,将模型类设置为JSON输出,并通过使用Swagger信息注释Scalatra路由来自动生成API文档。

    这是使用Swagger的一种方法,但Wordnik的变化方式却不同:不是从API开头而是使用Swagger只是生成文档,而是从手工编写JSON描述符文件开始。 然后,他们使用HTML docs浏览器查看API,并让所有对该API感兴趣的人士坐下来讨论所需的内容。 根据讨论更改JSON文件后,它们使用swagger-codegen生成客户端和服务器代码。 这称为接口驱动的开发 ,非常值得一看。 凭借其易用性,多框架集成以及使人们参与设计过程的创新方式,Swagger处于REST API构造工具的最前沿。

    代码

    您可以通过按照本教程开始时的详细说明安装Scalatra,执行git clone https://github.com/futurechimp/flowershop.git并在顶层运行sbt来下载并运行此应用程序的工作版本。该项目。

    翻译自: https://www.infoq.com/articles/swagger-scalatra/?topicPageSponsorship=c1246725-b0a7-43a6-9ef9-68102c8d48e1

    swagger 界面

    展开全文
  • vue-swagger-ui 接口文档界面 效果
  • Springcloud整合Swagger 界面查看Restful API说明: 这里使用的版本:springfox-swagger2(2.6.1)springfox-swagger-ui (2.6.1) 这里是说明常用注解的含义和基本用法 与Spring Cloud 微服务的集成 常用注解: -...

    Springcloud整合Swagger 界面查看Restful API

    说明:

    1. 这里使用的版本:springfox-swagger2(2.6.1)springfox-swagger-ui (2.6.1)

    2. 这里是说明常用注解的含义和基本用法

    3. 与Spring Cloud 微服务的集成

    常用注解:
    - @Api()用于类;
    表示标识这个类是swagger的资源

    • @ApiOperation()用于方法;
      表示一个http请求的操作

    • @ApiParam()用于方法,参数,字段说明;
      表示对参数的添加元数据(说明或是否必填等)

    • @ApiModel()用于类
      表示对类进行说明,用于参数用实体类接收

    • @ApiModelProperty()用于方法,字段
      表示对model属性的说明或者数据操作更改

    • @ApiIgnore()用于类,方法,方法参数
      表示这个方法或者类被忽略

    • @ApiImplicitParam() 用于方法
      表示单独的请求参数

    • @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

    1.启动类

    @SpringBootApplication
    @EnableDiscoveryClient //开启服务发现
    //@EnableCircuitBreaker //开启熔断器
    //@EnableFeignClients //开启声明式的web service客户端
    //@EnableTransactionManagement //开启声名式事务
    //@EnableCaching //启用缓存
    @ComponentScan(basePackages={"com.cloud.paas"})
    //@MapperScan("com.cloud.paas.portal.persistence") //扫描Mapper
    public class PortalApplication {
    
        /**   
         * @Title: main   
         * @Description: 启动类  
         * @param args
         */
        public static void main(String[] args) {
            new SpringApplicationBuilder(PortalApplication.class).web(true).run(args);
    
        }
    
    }

    2.加入swagger的相关依赖

            <!-- Swagger -->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.6.1</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.6.1</version>
            </dependency>

    3.初始化Swagger2的配置

    package com.cloud.paas.portal.configuration;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.ComponentScan;
    import org.springframework.context.annotation.Configuration;
    
    import com.google.common.base.Predicates;
    
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**  
     * @ClassName: Swagger2   
     * @Description: TODO  
     * @author: huangyan  
     * @date:2017年9月13日 下午2:15:43     
     */
    @Configuration  
    @ComponentScan(basePackages = { "com.cloud.paascontroller" })//配置controller路径
    @EnableSwagger2
    @SuppressWarnings({"unchecked","deprecation"})
    public class Swagger2Config {
        @Bean  
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)  
                    .apiInfo(apiInfo())  
                    .select()
                    .paths(Predicates.or( //这里添加你需要展示的接口
                            PathSelectors.ant("/account/**"),
                            PathSelectors.ant("/auth/**"),
                            PathSelectors.ant("/user/**"),
                            PathSelectors.ant("/test/**")
                                        )
                            )
                    .build();
    
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()  
                    .title("Spring Cloud")
                    .description("说明RESTful APIs")
                    .contact("330405457@qq.com") 
                    .version("1.0")
                    .build();  
        }
    }
    
    

    4.controller中加入swagger相应的注释

    @RestController
    @RequestMapping("account")
    @CrossOrigin
    @Api(description="账户接口")
    public class AccountNumberController extends BaseController{
    
        @Resource
        AccountNumberService accountNumberService;
    
        @ApiOperation(value="查询账户列表信息",notes="查询不同的条件,查询出账户的列表信息")
        @RequestMapping(value="/list",method=RequestMethod.POST)
        public Map<String,Object> list(@RequestBody AccountNumberCondition accountNumberCondition) {
            Map<String,Object> result = new HashMap<String,Object>();
            result.put("data", accountNumberService.list(accountNumberCondition));
            result.put("total", accountNumberCondition.getTotalRecord());
    
            return result;
        }
    
        @ApiOperation(value="查询单个账户信息",notes="根据账户id,查询出单个账户详细信息")
        @RequestMapping(value="/get",method=RequestMethod.POST)
        public AccountNumber get(@RequestBody String accountNumberId) {
            return accountNumberService.get(accountNumberId);
        }
    
    }

    5.浏览器中访问
    http://localhost:6002/swagger-ui.html

    如下图:这里写图片描述

    这里写图片描述

    展开全文
  • swagger 界面上进行调试就 OK 了,但是现在不管什么请求都要携带 token 信息,默认的 swagger 配置是没有的 我在上家公司的时候,当时的权限部门帮我们都做好了 token 验证,只要是能够进入到我们系统的用户,那就是有...

    我先说下背景:我最近不是换了家公司工作,然后这家公司就是不管发什么请求都是需要带着 token 信息的,也就是说,比如现在我写好代码了,想要验证我写的代码对不对,咱们现在用的都是 springboot , springcloud 框架,写完了直接在 swagger 界面上进行调试就 OK 了,但是现在不管什么请求都要携带 token 信息,默认的 swagger 配置是没有的
    我在上家公司的时候,当时的权限部门帮我们都做好了 token 验证,只要是能够进入到我们系统的用户,那就是有权限的,所以当时的项目直接在 swagger 界面上进行测试就 OK 了
    我刚接手项目熟悉的时候,想要测试一下请求, swagger 上没办法添加 token 信息,所以我就得用 postman 去测

    对我来说是有点儿难受的,你想想,我以前就是写好了接口,启动项目,去 swagger 项目上一测试,没问题提交代码完事儿,有问题我就可以直接进行调试
    现在使用 postman 测试没问题还好,有问题的话, token 不知道怎么添加进去,感觉就是明明可以直接使用 swagger 的,现在要再进行一个第三方 postman ,就感觉用的不是很顺手嘛

    所以我就想,能不能在 swagger 上直接就可以添加上 token 信息,这样的话,我就不需要再借助第三方工具 postman 了
    一倒腾还真的让我给搞成功了

    swagger 整合细节我就不说了,这里主要就是 swagger 启动那里需要设置,具体代码:

        @Bean
        public Docket controllerApi() {
            // 添加 head 参数配置 start
            ParameterBuilder token = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<>();
            token.name("Authorization").description("token 信息").modelRef(new ModelRef("String"))
                    .parameterType("header").required(false).build();
            pars.add(token.build());
            
            return new Docket(DocumentationType.SWAGGER_2)
                    .enable(enable)
                    .apiInfo(new ApiInfoBuilder()
                            .title(projectName + "接口文档")
                            .description(projectDesc + "")
                            .license("郑璐璐 csdn")
                            .licenseUrl("https://blog.csdn.net/zll_0405")
                            .version(version)
                            .build())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage(basePackage))
                    .paths(PathSelectors.any())
                    .build()
                    // 注意一下 globalOperationParameters 这行配置
                    .globalOperationParameters(pars);
        }
    

    OK ,添加好上面的代码之后,再启动就能在 swagger 界面上看到下面的改动了:
    在这里插入图片描述

    在图中红框框的地方,输入 token 信息,然后执行一下,你就会发现,使用 swagger 我又可以了,哈哈哈

    注意:给出的代码只是一个小 demo ,具体信息请根据自己的项目信息去配置
    以上,感谢您的阅读哇~

    展开全文
  • 在springboot中集成swagger,ui界面没有出来,后台报错 swagger No mapping for GET /swagger-ui.html 查了下,需要在拦截器里面添加如下配置, @Override protected void addResourceHandlers...

    在springboot中集成swagger,ui界面没有出来,后台报错

    swagger  No mapping for GET /swagger-ui.html

    查了下,需要在拦截器里面添加如下配置,

       @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }

    展开全文
  • 遇到一个问题:swagger界面 @RequestBody 参数类错误,变成了其他参数类,不是相应的类,看类写的没错,属性都没错,检查半天 结果原因是:有两个类的注解值一样的,这种问题一般是复制问题,或多人开发写的问题 ...
  • client: 配置文件中添加status-page-url: http://localhost:${server.port}/swagger-ui.html#/ 依赖: ...-- swagger2 --> <dependency> <groupId>io.springfox</groupId> ...
  • springcloud整合swagger 图形化界面查看restful api
  • 目录缘由原生SwaggerKnife4J 缘由 接口文档想必是许多开发小...但是,对界面审美有要求的前端同学,又吐槽Swagger原生界面太low了,而且功能还少。 有压迫就有反抗,后端肯定不服,既然你嫌弃原生Swagger太low,那就给
  • //swagger2 filterChainDefinitionMap.put("/swagger-ui.html", "anon"); filterChainDefinitionMap.put("/swagger-resources/**", "anon"); filterChainDefinitionMap.put("/v2/api-docs/**", "anon"); fi....
  • 配置中加入: ...eureka.instance.status-page-url: http://${spring.cloud.client.ip-address}:${server.port}/swagger-ui.html#/ 注意: 如果缺少开头的http://会导致在eureka界面的链接无法点击。 ...
  • 之前我们在写项目的实体类的时候,只是简单的写一个实体类,但是现在我们想要让实体类在swagger界面显示, 首先是写一个实体类 只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中: @ApiModel(...
  • 在启动abp框架后不用手动再指定URl可通过修改HomeController
  • import org.springframework.beans.factory.... } 问题待解决 sendMessage方法加了swagger注解后,swagger界面就不会显示接口列表,但是页面可以进去,网页报错如图: 。。。。。。。。。。。。。。。 解决办法 暂无
  • swagger界面非必传参数的设置

    千次阅读 2019-04-13 10:13:00
    修改之前:第一次代码实现: @RequestMapping(path="/getByStoreAndTypeAndSn/{storeId}/{versionType}/{terminalSn}", method=RequestMethod.GET ) public TerminalSet getListByStoreIdAndVersionAndSn(@...
  • 在使用Swagger的时候,你是否会有这种感觉:提交参数为JSON没法格式化,参数错了查找麻烦,返回结果没法折叠,太长了没法看!Swagger结合Postman使用后这一情况有很大改变,今天我们来讲下如何使用Postman增强...
  • 在做CRMEB-JAVA开源商城系统时,我们团队用到了uni-app,也是时下比较流行的移动端开发技术,这里边就牵扯到了前后端全部分离的问题,一般在使用java开发前后端分离项目的时候,都会用到SwaggerSwagger 是一个用于...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 9,438
精华内容 3,775
关键字:

swagger界面