xiaodongw / swagger-finatra

Finatra Swagger Support

swagger-finatra

Add Swagger support for Finatra (1.6 and 2.2.0) web framework.

It requires Java 8 from version 0.6.0.

Getting started

Gradle

Add repository

repositories {
  maven { url "https://oss.sonatype.org/content/repositories/releases/" }
}

Add Dependency

Scala 2.10, Finatra 2.2.0

compile "com.github.xiaodongw:swagger-finatra_2.10:0.7.2"

Scala 2.11, Finatra 2.2.0

compile "com.github.xiaodongw:swagger-finatra_2.11:0.7.2"

SBT

resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/releases/"

Add Dependency

Finatra 2.2.0

libraryDependencies += "com.github.xiaodongw" %% "swagger-finatra" % "0.7.2"

Add document information for you controller

object SampleSwagger extends Swagger

class SampleController extends Controller with SwaggerSupport {
  implicit protected val swagger = SampleSwagger

  getWithDoc("/students/:id") { o =>
    o.summary("Read the detail information about the student")
      .tag("Student")
      .routeParam[String]("id", "the student id")
      .responseWith[Student](200, "the student details")
      .responseWith(404, "the student is not found")
  } { request =>
    ...
  }

Add document controller

Finatra 2.2.0

object SampleApp extends HttpServer {
  val info = new Info()
    .description("The Student / Course management API, this is a sample for swagger document generation")
    .version("1.0.1")
    .title("Student / Course Management API")
  SampleSwagger.info(info)

  override def configureHttp(router: HttpRouter) {
    router
      .add[WebjarsController]
      .add(new SwaggerController(swagger = SampleSwagger))
      ...
  }
}

Swagger API document: http://localhost:8888/api-docs/model

Swagger UI: http://localhost:8888/api-docs/ui

Finatra 1.6

Previous version of Finatra (1.6) is also supported, Check here for the guide.

swagger-finatra's Issues

Typo in SwaggerSupportBase

In this line: val finatraSwager: FinatraSwagger // expected swagger (in readme), but actual swager
Please fix it.

Ability to specify JSON mapper

Currently you use the swagger json mapper, wouldn't it be better to use the included finatra mapper (with the option to use @CamelCaseMapper)? I use the default finatra functionality when it comes to mapping values, so my requests look like:

{
    "a_very_important": "value"
}

instead of

{
    "aVeryImportant": "value"
}

And I don't see a way currently to support the first without writing name annotations on every request case class. if you don't have time, are you open to a PR surrounding this?

support xml format

Is there any way to show xml format on swagger document?

Can't use multiple filter

filter[AFilter]
  .filter[BFilter]
  .filter[CFilter]
  .getWithDoc("..."){....}{...}

it occurs error

Error:(27, 12) method filter: (next: com.twitter.finatra.http.HttpFilter)com.twitter.finatra.http.RouteDSL does not take type parameters.
    .filter[BFilter]

Publish 0.7.2 with bugfix

Can you publish a new version with the bugfix I submitted?

Support finatra 2.6+

The AdminIndexInfo class has been removed in finatra 2.6 and now uses RouteIndex instead. Can we publish a version of swagger-finatra to support this change?

https://github.com/twitter/finatra/releases/tag/version-2.6.0

Not updated 0.3.0 on maven.

Thanks for awesome project. 👍
I want to put in my project, but in maven it's still on 0.2.0

I think it should be update. Thanks.

Support 2.8 prefix route

2.8 supports api route prefixes. It'd be great to support this feature as well

Unable to reference the SwaggerSupport method when using per route filters.

filter[SomeFilter]
    .post("/apps", swagger { o =>

    }) { app: CreateApp =>
      appService.create(app).asTwitter
    }

How can this be done?

get missing parameter type when following the sample code in readme.

[error] /Users/yaochin/Code/git/battleship/battleship-server/src/main/scala/com/yaochin/battleship/controller/SampleController.scala:19: missing parameter type
[error]   } { request =>
[error]       ^
[error] one error found
[error] (server/compile:compileIncremental) Compilation failed

should it be request: Request?

Upgrade to Finatra 2.1.1

Finatra 2.1.1 is out, the break change is finagle-httpx is renamed back to finagle-http.

Cross-compile for 2.12 and release

Can't use this project currently because it's not compiled against 2.12.

Typo in README, .register, but .add

You wrote register(new SwaggerController()) for Finatra 2, but this method with expected signature does not exists.
It should be .add(new SwaggerController()).
I found the correct line in your test (SampleApp.scala)

swagger-finatra can't work with finatra 2.6.0

I'm using Finatra 2.6.0 with swagger-finatra 0.6.0. I got error when compile.
Some part of error message as follow:

[error] missing or invalid dependency detected while loading class file 'SwaggerRouteDSL.class'.
[error] Could not access type AdminIndexInfo in package com.twitter.finatra.http.routing,
[error] because it (or its dependencies) are missing. Check your build definition for
[error] missing or conflicting dependencies. (Re-run with -Ylog-classpath to see the problematic classpath.)
[error] A full rebuild may help if 'SwaggerRouteDSL.class' was compiled against an incompatible version of com.twitter.finatra.http.routing.
[error] one error found
[error] (compile:compileIncremental) Compilation failed

Then I find the CHANGLOG at Finatra 2.6.0, They remove the c.t.finatra.http.routing.AdminIndexInfo
Can't you help this issue?

Be able to set 'validatorUrl' in swagger-ui

In my project, I want to be able to customize the validatorUrl. I should have a PR for this soon :)

File formParam

Unless I'm doing this incorrectly, seems like file upload isn't supported yet.

Example in pet store: https://github.com/swagger-api/swagger-codegen/blob/master/samples/client/petstore/akka-scala/src/main/scala/io/swagger/client/api/PetApi.scala#L128-L133

Example in ui: http://petstore.swagger.io/#!/pet/uploadFile

I've tried both a case class with a dataType file, and specifying File as the TypeTag.

Finatra 2.0 Swagger

Hello,

I'm using the swagger stuff like below, but I get "/api-docs route not found" when doing localhost:8888/api-docs (8888 is the http port Finatra starts under).

object Server extends SomeServer

class SomeServer extends HttpServer {

  FinatraSwagger.registerInfo(
    description = "My endpoint for various APIs.",
    version = "0.0.1-SNAPSHOT",
    title = "My RESTful API!"
  )

  override def modules = Seq(LogbackModule)

  override def configureHttp(router: HttpRouter): Unit = {
    router
      .add[TheController]
  }
}

Any ideas?

Thanks,
Alex

Filter finatra annotations in bodyParam

If you have a body param of:

case class PingPostRequestWithRoute(
   @RouteParam name: String,
  data: String
)

And a controller of:

postWithDoc("/api/v1/ping/:name") {
    _.responseWith[PingResponse](200).
      routeParam[String]("name").
      summary("Ping").bodyParam[PingPostRequestWithRoute]("body").
      tag("test")
  } { request: PingPostRequestWithRoute =>

    PingResponse(request.data + thing.name)
  }

The correpondsing swagger body has

Which incorrectly uses the route param. This has even more repercussions when you have an @Inject request: Request param since it blows up the jackson introspection

To work around this you have to add a class level annotation

JsonIgnoreProperties(Array("fieldName"))

To the payload class. This means that you have to type the route/query/body fields 3 times to get it to properly register. Once in the json ignore, once in the swagger param, and once in the actual payload class

Can we filter these properties or provide a more unified way of registering the params? The finatra way seems to create a single object representing the entire request (queryparams/routeparams/bodyparams). If we could generate the swagger off of that by adding in extra annotations (like the way jersey/dropwizard does it) that would be killer

Maybe something like:

case class PingPostRequestWithRoute(
   @Description("The name for the route")  @RouteParam name: String,
   @Description("The body payload") data: String
)

postWithDoc("/api/v1/ping/:name") {
    _.responseWith[PingResponse](200).    
      summary("Ping").
      request[PingPostRequestWithRoute]. // enough metadata is here to build the swagger request info
      tag("test")
  } { request: PingPostRequestWithRoute =>

    PingResponse(request.data + thing.name)
  }

Option not being mapped to definition correctly

I'm not sure if this is a swagger-scala-module bug or swagger-finatra bug but it appears that Option containers are not being converted correctly into swagger. I have this finatra controller definition:

case class Person(maybeName: Option[String], age: Int)

getWithDoc("/v1/derek") { o =>
  o.summary("Return me!")
    .responseWith[Person](200, "Person")

} { request: Request =>
  response.ok.json(Person(Some("Derek"), 24))
}

Definitions section in the model.json created by swagger:

  "definitions": {
    "Option": {
      "type": "object",
      "properties": {
        "empty": {
          "type": "boolean"
        },
        "defined": {
          "type": "boolean"
        }
      }
    },
    "OptionString": {
      "type": "object",
      "properties": {
        "empty": {
          "type": "boolean"
        },
        "defined": {
          "type": "boolean"
        }
      }
    },
    "Person": {
      "type": "object",
      "properties": {
        "maybe_name": {
          "$ref": "#\/definitions\/OptionString"
        },
        "age": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  }

Is there a workaround for this?

ApiModelProperty annotation unexpected result

I used swagger ApiModelProperty annotation in my Model declaration, but some fields in annotation not working in api-docs result e.g: required, example, reference, allowableValues.

Did I try something unimplemented featues? or it should work correctly? Thanks.

Model documentation is missing

There doesn't seem to be a way to annotate models (case classes). If there is, please document it in the README.