Can't Use @ApiModelProperty on case classes properties

[alberto2perez]

Hello @pjfanning , thanks for the great work with this example

I am reaching you out because I am trying to use @ApiModelProperty following the instructions specified here https://github.com/swagger-akka-http/swagger-akka-http#model-definitions but it's not working, all I get is Type not found errors for @apimodel and @ApiModelProperty annotations

I am interested in Swagger-2.0 branch of this project as an example to generate OpenApi 3.0.0

Do you have any experience or could point me the right direction on how properly use those annotations in this project?

I am trying this code.

@ApiModel( description = "Add Request object")
  case class AddRequest(
                         @ApiModelProperty( value = "numbers", example = "999", dataType = "string")
                         numbers: Array[Int]
                       )

FYI I also tried to install swagger-jaxrs2 (https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-jaxrs2/2.0.0)

libraryDependencies += "io.swagger.core.v3" % "swagger-jaxrs2" % "2.0.0"

But didn't have any luck with that, the same error keeps coming up.

I really appreciate your help in advance.
Thanks

[pjfanning]

https://github.com/pjfanning/swagger-akka-http-sample/blob/enum-sample/src/main/scala/com/example/akka/echoenum/EchoEnumService.scala

This branch uses model annotations.

[alberto2perez]

Thank you @pjfanning for your fast response, I really appreciate it.

Right now I am using it just like that but I was trying to migrate to Swagger 2, the main reason is that I want to use the new annotation @Operation to specify the request body as a full JSON object instead of a list of parameters, I didn't find a way to get it work with "com.github.swagger-akka-http" %% "swagger-akka-http" % "0.14.0" (which is the version of the enum-sample branch), I spent some time trying to do it but didn't make it, maybe you can give me some light in that direction.

I want to be able to do something like

    @Path("/authenticate")
    @Operation(summary = "Authenticates a client",
        requestBody = new RequestBody(content = Array(new Content(schema = new Schema(implementation = classOf[ClientName]), mediaType = "application/json"))),
        responses = Array(
            new ApiResponse(
                responseCode = "200",
                description = "Add response",
                content = Array(new Content(schema = new Schema(implementation = classOf[ClientName]), mediaType = "application/json"))
            ),
            new ApiResponse(responseCode = "500", description = "Internal server error"))
    )

FYI: comments in the code doesn't makes sense, its just an example while I was testing.

Swagger-2.0 branch was my starting point for the migration and it went pretty straightforward until I hit this issue

This is the first time I use Swagger so apologize for the lack of experience with this, I appreciate in advance any insight you can give me.

[pjfanning]

Did you look at the swagger 2.0 branch - it uses a snapshot version of swagger-akka-http that supports openapi 3.
There is a lot of work needed to complete this and I don't have time right now.

[alberto2perez]

Yes, my issue started there, taking that branch swagger 2.0 as an example, I was able to describe my request as a JSON object using OpenApi 3 but then I can't get to work my models annotations.

I couldn't find any place where being used OpenApi 3.0 and those Annotations together using swagger-akka-http, I am stuck.

Thank you a lot for your help.

[pjfanning]

I tried https://github.com/pjfanning/swagger-akka-http-sample/tree/swagger2-enum and the Parameter annotation on the case class EchoEnum doesn't seem to get picked up.
The code that generates the swagger models is in swagger-jaxrs2 - it might be worth reporting an issue there.
NB swagger 2.0.0 is very different from swagger 1.5.x and that the annotations have changed a lot.
I am on vacation for a few weeks so do not have time to follow up.

[alberto2perez]

Hello @pjfanning,

Thank you for taking time to help me with this issue, I appreciate it especially on your vacations, I hope you are having a great time.

I was looking at your example and also here https://github.com/swagger-api/swagger-samples/tree/2.0

And, to my surprise, I found that using @Schema directly instead of @Parameter works for the result I want to achieve.

Here is the sample piece of code

case class EchoEnum(
   @Schema( required = true, example = "GRANDE", allowableValues =  Array("TALL", "GRANDE", "VENTI"))
   enumValue: Enum.Value
  )

And here the result

    Value:
      type: object
      example: GRANDE
      enum:
      - TALL
      - GRANDE
      - VENTI
   EchoEnum:
      required:
      - enumValue
      type: object
      properties:
        enumValue:
          $ref: '#/components/schemas/Value'

Again, thank you so much for your help and support, I am closing this issue.

Have a great time.

[alberto2perez]

Hello again @pjfanning

I wanted to comment out here, just FYI, maybe you can point me in the right direction, I am struggling for a while with an issue with properties of type Option[T] not showing the specified example.

The output YML will show all examples accordingly under the ClientName schema

case class ClientName(
              @Schema(description = "First Name", example = "John")
              firstName: String
              @Schema(description = "Middle Name", example = "")
              middleName: String,
              @Schema(description = "Last Name", example = "Doe")
              lastName: String,
)

however, this one won't, the only difference is the type of the properties.

case class ClientName(
              @Schema(description = "First Name", example = "John")
              firstName: Option[String],
              @Schema(description = "Middle Name", example = "")
              middleName: Option[String],
              @Schema(description = "Last Name", example = "Doe")
              lastName: Option[String],
)

Please, I appreciate any information you can give me, I've been looking everywhere but without luck.

Thanks in advance

[pjfanning]

Swagger-akka-http is a tiny codebase that depends on swagger-api jars and Jackson databind. There are type erasure issues with Scala options. In the end, it seems likely that we will need to rewrite large amounts of code yo support Scala reflection instead of Java reflection. There is no community formed to support this right now. This whole project is no longer a priority for me.

[pjfanning]

In the ClientName class Schema annotations, you could have type=string, required=false

[alberto2perez]

Thank you @pjfanning for taking time to answer, I really appreciate it.

Regarding your recommendation, I already tried that, as you said, it looks like a bug somewhere deeper, and reading around I found someone saying on Stackoverflow that he solved it by having two classes one for the examples (without using Option[T]) and the real class, but it looks like a very nasty solution. I've I tried many other combinations without success.

Unfortunately, I am moving from 10 years of PHP to Scala/Java and I am going through the learning curve, I still don't dare to try to rebuild or help in something like that, I do notice the community is very small and there are not too many people contributing, but I recognized the power of Scala at first sight, I know that will improve dramatically within the next years.

I really appreciate the time you take to help others, any other advice will be welcome.