Scalatra Swagger POST body

[Nuno Castro]

I'm using Scalatra and Swagger to create my REST API. When it comes to GET requests, it is easy to clearly define the parameters (required/optional and enumerate the possible values). However, when you are using a POST request, the only parameter that you can declare is the bodyParam[YourCaseObject]("body"). 

Say you are passing a user object in the request body:

 

{ "userid" : "1", "username": "john" } which is extracted by

case class User(val userid : String, val username, val optional1 : String = "", val optional2 : Int = -1)

My question is how can you state which fields are optional/required, enumerate their values (e.g. optional1 can be ["a","b","c"]), and provide an appropriate user response when one of the required fields is missing. I've tried using the @ApiProperty annotation, but its result is not shown in the Swagger Web UI. 

 

[tony tam]

You can use both path & get params along with a POST body, but I don't think that's your question.  The parameters inside the object being posted (User in your example) can be annotated with @ApiProperty(required=false) and allowable values, see here:

https://github.com/wordnik/swagger-core/blob/master/samples/scala-scalatra/src/main/scala/com/wordnik/swagger/sample/model/Models.scala#L7

They are *not* however picked up in the swagger-ui, which is something that will come soon.  They *will* be used by the swagger-codegen, though.

The Option[_] should translate into "required=false" shortly, but that's currently not supported.

Hope that clarifies things for you

[Nuno Castro]

Thanks for your response Tony.

It's great that it will be supported.

Now that you mention the codegen, I didn't fully understand what is the process of generating the REST API using the codegen.

At the moment I fully describe my REST API in the Servlet class and respective case User class, e.g.:

val user =

    (apiOperation[UserResponse]("user")

      summary "Sends an user"

      notes "Sends an users information, aiming to inform the system."

      parameter bodyParam[User]("body").description("An user.").required)

  post("/user", operation(user)){

    parse(request.body).extractOpt[User] match {

      case Some(anUser) => UserController.insertUser(anUser)

      case _             => halt (501, "Invalid User.")

    }

  }

Is this standard procedure? Or should I be describing my user using JSON and then using the codegen to create the servlet code?

How can I inform the user that a missing required field (e.g. userid) is missing? Do I have to access the parsedBody map and check it manually?

Thanks 

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/PMcciPohq2k/unsubscribe?hl=en.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[tony tam]

Hi, what you show is a good way to parse the post body--one technique to handle the extraction is to write a custom deserializer which can handle missing values, or do better validation.

The codegen is for creating a consumer of your api

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Nuno Castro]

Thanks, I'll look into it.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[tony tam]

here's a gist that might help get you going on custom deserializers with json4s

https://gist.github.com/fehguy/4191861#file-gistfile1-scala-L74

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.