Swagger-core: 1.5.x: ApiImplicitParams annotation is ignored

Created on 10 Mar 2015 · 52Comments · Source: swagger-api/swagger-core

When I first noticed this bug I thought it happens only when I use ApiParam _and_ ApiImplicitParams at the same time.

Looks like ApiImplicitParams is ignored in any case. As result I can't document security token which intercepted by servlet filter earlier.

Here is endpoint

@GET
@Consumes("text/plain")
@Produces(MediaType.APPLICATION_JSON)
@Path("testParams")
@ApiOperation(response = String.class, value = "Returns string with provided parameter")
@ApiImplicitParams({@ApiImplicitParam(name = "token", required = true, dataType = "string", paramType = "query", value = "API token")})
public String testParams(@ApiParam(required = false, value = "ID of timesheet") @QueryParam("id") int id) {}

Example project is located at
https://github.com/cppexpert/broken_swagger_jaxrs_integration

Bug P1

Source

unoexperto

All 52 comments

Will check that, but spec-wise, you're probably better off describing it as a security definition and not as an operation parameter.

webron on 10 Mar 2015

According to earlier conversation here (in another issue) security definition is not going to work for me for multiple reasons one of which is lack of support of unauthenticated endpoints.

unoexperto on 10 Mar 2015

Can you refer me to that discussion please?

webron on 10 Mar 2015

https://github.com/swagger-api/swagger-core/issues/889

And even "api_key" wasn't working in my sample app anyway. Filling out that field in swagger-ui never passed it with the request.

unoexperto on 10 Mar 2015

Hi Ron! Could you please tell me what rough ETA for the fix is ?
Thanks!

unoexperto on 14 Mar 2015

A release should be around next weekend. The fix may be available earlier via a snapshot.

webron on 14 Mar 2015

How is it going with new release, guys ? This bug is quite critical too https://github.com/swagger-api/swagger-core/issues/847

unoexperto on 23 Mar 2015

Hi @cppexpert M2 is off by a week. I can certainly do a point release of M1.

Watch for 1.5.3-M1 in a bit.

fehguy on 23 Mar 2015

1.5.3-M1 is now released. It should appear in maven central shortly

fehguy on 23 Mar 2015

But neither #847 nor #905 are fixed in 1.5.3-M1, right ?

unoexperto on 23 Mar 2015

Implicit params are supported (was the original issue posted here). Did you look at the fix in the sample project you provided?

The model issue #847 is not quite done yet.

fehguy on 23 Mar 2015

I tried using 1.5.3-M1 with my work project. Implicit parameters are still not visible.

unoexperto on 6 Apr 2015

I am having the same problem with the ApiImplicitParam annotation. I spent some time looking over the latest code (1.5.0-M2) and couldn't see any references to this annotation in any of the source code. I did see a reference in the old 1.3.12 code (in the JaxrsApiReader.scala class). I think the equivalent class for 1.5 would be the Reader class, but couldn't find an equivalent code block.

sanchopancho13 on 7 Apr 2015

This implicit parameter code path should be well tested. If you can please provide an example of what is not working we can figure it out.

fehguy on 7 Apr 2015

Hi @fehguy. The simplest test I could devise was the following:

1) Downloaded the latest swagger-core code from master (which is currently 1.5.1-M2).
2) In the samples/java-jaxrs project, edited the PetResource class by adding the following annotation to the getPetById method:

  @ApiImplicitParams({
      @ApiImplicitParam(name = "sort", paramType = "query", dataType = "string", required = false, value = "Comma-delimited list of fields to sort by.")
  })

3) [I also changed the description of the operation to make sure that I was seeing my latest changes.]
4) Ran the sample project with the maven jetty command.
5) Viewed the new documentation in a local swagger-ui instance. The implicit parameter is not displayed.

sanchopancho13 on 7 Apr 2015

Any update on this issue? It seems that there is no reference of @ApiImplicitParams in source code even though the documentation is complete.

buremba on 24 Apr 2015

👍1

Yes, it's a defect. Working on it.

fehguy on 24 Apr 2015

Any update on this? Can I help at all ?

who on 14 May 2015

It will be handled soon.

webron on 14 May 2015

sorry, maybe a bit off the topic, I also ran into an issue with @ApiParam swagger-core 1.5.1-M2. I wrote a customized SwaggerSpecFilter to filter out some internal param. Whenever I tried to access the "access" property of Parameter in method isParamAllowed, it's alway null. Is this feature missing in 1.5.1-M2?

Thanks,

thegreatdao on 19 May 2015

Can anyone offer insight on where the fix needs to happen? I need this a.s.a.p. and am happy to fix it myself but some pointers in the right direction would greatly help.

alexworden on 19 May 2015

👍1

It's a whole set of logic that needs to he added to the Reader.java.

webron on 19 May 2015

@webron How is the progress by the way? It's been two months :)

unoexperto on 19 May 2015

It's going great, thank you :) Seriously though, I believe we could get it done next week. This week may prove to be difficult.

webron on 19 May 2015

I'm currently doing some stuff in the Reader for another issue, if you can bring me up to speed on this one I can probably fix it as well...

olensmar on 19 May 2015

@olensmar - sure, we'll talk about it offline

webron on 19 May 2015

initial code is at https://github.com/swagger-api/swagger-core/compare/develop_2.0...issue-905-implicit-params - please let me know what I missed...

olensmar on 28 May 2015

This is now merged in develop_2.0. Will be released soon.

webron on 3 Jun 2015

Wow, I'll get wasted today if it works.

unoexperto on 3 Jun 2015

😄1

Haha, it should work, but if you can test the develop_2.0 branch quickly and provide us feedback, that would be great because we want to make a public release very soon.

webron on 3 Jun 2015

yeah - feedback would be awesome - thanks!

olensmar on 3 Jun 2015

I'll try to test it today and will let you know.

Sent from my iPhone

On Jun 3, 2015, at 12:18 PM, Ron [email protected] wrote:

Haha, it should work, but if you can test the develop_2.0 branch quickly and provide us feedback, that would be great because we want to make a public release very soon.

—
Reply to this email directly or view it on GitHub.

alexworden on 4 Jun 2015

@alexworden - thanks!

webron on 4 Jun 2015

I tried to verify today but I'm using the swagger-maven-plugin to build the
spec at compile time.
Currently, I can't get that project to build, so I can't update the version
of swagger it uses.

I don't have time to spin my wheels in this right now sorry.

On Wed, Jun 3, 2015 at 3:02 PM, Ron [email protected] wrote:

@alexworden https://github.com/alexworden - thanks!

—
Reply to this email directly or view it on GitHub
https://github.com/swagger-api/swagger-core/issues/905#issuecomment-108628033
.

alexworden on 9 Jun 2015

Hi all, I'm also experiencing that issue with swagger-play2 version 1.3.12. When do you think it could be fixed?

Thanks

prota on 10 Jul 2015

@prota - this is unrelated. The issue is on the 1.5.X branch. Unfortunately, we no longer issue new releases for the 1.3.X branch.

webron on 10 Jul 2015

@webron Just to let you know. I just tested "io.swagger" % "swagger-jersey2-jaxrs" % "1.5.0" and ApiImplicitParams is still not working.

Here is json I get
http://dpaste.com/3CNDBYE

Here is one of the classes defined

@SuppressWarnings("VoidMethodAnnotatedWithGET")
@Path("taskSchedule")
@Api(value = "taskSchedule", description = "Operations with scheduled resources", produces = "application/json")
@Authenticated
public class TaskScheduleRoutes extends AbstractRoutes {

    @GET
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(response = ListResponseWithUpdate.ModifiedTimesheetEntriesResponse.class, value = "Returns multiple task schedules")
    @ApiImplicitParams({@ApiImplicitParam(name = "token", required = true, dataType = "string", paramType = "query", value = "API token")})
    @ManagedAsync
    public ListResponse<TaskScheduleWire> getTaskSchedules(
            @ApiParam(required = true, value = "Comma separated IDs of task schedules") @QueryParam("ids") String idsStr,
            @Suspended final AsyncResponse response) {

        Precondition.checkArgument(idsStr != null && !idsStr.isEmpty(), "`ids` is missing or empty");

        final ArrayList<String> ids = Lists.newArrayList(idsStr.split(","));

        // Basic sanity check
        Precondition.checkArgument(ids.size() > 0, "Array with IDs is empty or not provided");

        return handleInFuture(() -> {
            Collection<TaskSchedule> items = api.getTaskSchedules(ids.stream().map(Long::valueOf).collect(toSet()));
            return new ListResponse<>(items.stream().map(TaskScheduleWire::fromTaskSchedule).collect(toList()));
        }, response);
    }
}

Any thought when it can finally be fixed ?

unoexperto on 10 Jul 2015

Considering others have reported other bugs related to @ApiImplicitParam, it means that they are now successfully scanned and processed (definitely not ignored). If you're still experiencing an issue, feel free to open a new ticket and we'll see how we can investigate it.

webron on 10 Jul 2015

@webron Why should I file new ticket if from my POV it's being ignored. I don't and can't know whether it's "really scanned" in the library. All I see is that token param is not presented in generated Swagger json.

unoexperto on 10 Jul 2015

I took the sample you shared in the original post, updated the dependencies, package names and imports, and it loads the implicit parameter just fine. You may have missed something in the process, I don't know what. Make sure you update the web.xml as well (com.wordnik.swagger... -> io.swagger...).

webron on 10 Jul 2015

@cppexpert I think your dependency isn't right. Please try this:

"io.swagger" % "swagger-jersey2-jaxrs" % "1.5.1-SNAPSHOT"

That is where the fix lives. Let us know?

fehguy on 13 Jul 2015

@fehguy Is there custom repo I can point to ? It's not in genereal maven repo.

unoexperto on 14 Jul 2015

Yes, please try sonatype snapshots:

"sonatype-snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"

fehguy on 14 Jul 2015

Actually, the fix is available in 1.5.0.

webron on 14 Jul 2015

@fehguy Tony, for some reason it can't fetch swagger-models. Perhaps there is wrong reference in parent POM ? Here is what SBT says

[warn] ==== sonatype-snapshots: tried
[warn]   https://oss.sonatype.org/content/repositories/snapshots/io/swagger/swagger-models/1.5.1-SNAPSHOT/swagger-models-1.5.1-20150716.064150-10.pom
[warn]   https://oss.sonatype.org/content/repositories/snapshots/io/swagger/swagger-models/1.5.1-SNAPSHOT/swagger-models-1.5.1-SNAPSHOT.pom
[warn] ==== spray releases: tried

unoexperto on 17 Jul 2015

I do see it here:

https://oss.sonatype.org/content/repositories/snapshots/io/swagger/swagger-models/1.5.1-SNAPSHOT/

I'll republish the snapshot though. Try again?

fehguy on 20 Jul 2015

It works! Thanks!

unoexperto on 28 Jul 2015

@cppexpert, I tried all the solutions I could find to make the @ApiImplicitParam work, but I have failed. I'm using swagger-jersey-jaxrs 1.5.3-M1. Which version have you used to make it work?

titiu7 on 3 Aug 2015

@titiu7 I'm on "io.swagger" % "swagger-jersey2-jaxrs" % "1.5.1-SNAPSHOT" from sonatype snapshots. Just to confuse everyone even more they published latest build with changed package name and _lower_ version number :)

unoexperto on 3 Aug 2015

@cppexpert it's confusing for sure. I changed the group id to io.swagger and it works. Thanks

titiu7 on 4 Aug 2015

I just wanna know in annotation @ApiImplicitParam how to describe a parameter's length.Such as there is a parameter is String and I wanna the client who send a request know what is the max length and min length of this string by swagger? Thank you.