Hi David,

I could use some guidance here actually on whether to keep the @Parameter annotation.  The plan was to deprecate it, but I'm willing to keep it in.

The "new" approach is to annotate your parameters on the method arguments like so:  

@RestMethod(name="GET",
    path="/foo/{somePathParam}/*",
    properties ={
        @Property(name=HTMLDOC_header, value="$L{title}")
    }
)
public ServiceResult someMethod(
        RestRequest request,
        RestResponse response,
        @Path(
            name="somePathParam",
            description="xxx"
        )
        String somePathParam) {
       ...
   }

The @MethodSwagger(parameters) annotation is thus really not needed anymore, but the Simplified-JSON syntax for defining it is provided as a free-form way of doing so.  The @Parameter annotation didn't include all possible Swagger values, so this was a way to "keep up with the spec" if you wanted to define the parameters in the @MethodSwagger like so:

@RestMethod(name="GET",
    swagger=@MethodSwagger(
        parameters={
            "{name:'somePathParam',in:'path',description:'xxx'}"
        }
    )
)

However, parameters defined like this are considered "documentation only", meaning you don't get auto-validation of parameter values.  That's actually part of the design because it allows you to provide either validating or non-validating Swagger.  For example, 

// Validating
@Path(
    name="somePathParam",
    description="xxx",
    minLength=10, maxLength=20
)

// Non-validating
@RestMethod(name="GET",
    swagger=@MethodSwagger(
        parameters={
            "{name:'somePathParam',in:'path',description:'xxx',minLength:10,maxLength:20}"
        }
    )
)

As far as keeping @Parameter, I could re-add it using a separate "parameters2" attribute like so:
@RestMethod(name="GET",
    swagger=@MethodSwagger(
        parameters2={
            @Parameter(....)
        }
    )
)

My concerns with that though are that we're defining two separate ways of defining free-form parameters.  And the existing @Parameter annotation didn't get the Swagger spec exactly correct (it was an amalgam of "body" and the other parameter types which only has some overlap in Swagger). 

I'm not sure why you're seeing that "@Path used without name or value" error.  I'll see if I can reproduce that.  The workaround is to add the name of your path parameter like so:

public ServiceResult someMethod(
    RestRequest request,
    RestResponse response,
    @Path("somePathParam") String somePathParam) {
      ...
   }
 

On Thu, Oct 25, 2018 at 2:32 PM David Goddard <goddard@acm.org> wrote:
Hi,

I'm catching up with some of the 7.2.0 changes and I'm hitting some
issues updating some pre-7.2.0 code (specifically I'm having problems
similar to JUNEAU-85).

I note that org.apache.juneau.rest.annotation.Parameter was removed from
7.2.0 as part of the Swagger changes (although not all of the
documentation seems to have caught up:
http://juneau.apache.org/site/apidocs/org/apache/juneau/rest/annotation/MethodSwagger.html#parameters--)

So my original code was like:

   swagger = @MethodSwagger(
     parameters= {
       @Parameter(in="path", name="somePathParam", description="xxx"),
     }
    ),

This would obviously fail in 7.2.0 as @Parameter is absent.

However, I'm hitting some issues getting it working with the
SimplifiedJson syntax described in
http://juneau.apache.org/site/apidocs/org/apache/juneau/rest/annotation/RestMethod.html#swagger--,
which is of this format as per the docs:

   swagger={
     "parameters:[",
       "{name:'propertyName',in:'path',description:'The system property
name.'},",
       "{in:'body',description:'The new system property value.'}",
     "],",
     "responses:{",
       "302: {headers:{Location:{description:'The root URL of this
resource.'}}},",
         "403: {description:'User is not an admin.'}",
      "}"
    }

So my method updates to something like this:

   @RestMethod(name="GET", path="/foo/{somePathParam}/*",
guards=FooGuard.class,
     swagger = {
       "parameters:[",
         "{name:'somePathParam',in:'path',description:'xxx',required:true}",
       "],"
     },
     properties = { // some props }
   )
   public ServiceResult someMethod(RestRequest request, RestResponse
response, @Path String somePathParam) {
        // etc.
   }

However, this gives me a syntax error in Eclipse:

   Type mismatch: cannot convert from String[] to MethodSwagger

Any idea what I'm doing wrong here? (I am assuming I'm doing something
wrong)

Looking at the Pet Store example code, I see a different syntax in
PetStoreResource, leading me to change my method to this:

   @RestMethod(name="GET",
       path="/foo/{somePathParam}/*",
       properties ={
         @Property(name=HTMLDOC_header, value="$L{title}"),
       },
       swagger = @MethodSwagger(
         parameters= {
            "{name:'somePathParam',in:'path',description:'xxx'}",
         }
       )
   )
   public ServiceResult someMethod(RestRequest request,
                   RestResponse response,
                   @Path String somePathParam) {
       return null; //(Not really)
   }

Do we have a documentation issue, or an understanding issue on my part?

However, in any case I get a runtime error at the moment:

#######
Exception occurred while initializing method
'some.package.ServiceREST.someMethod'
...
Caused by: @Path used without name or value on method
'some.package.ServiceREST.someMethod(RestRequest,RestResponse,String)'
parameter '2'.
#######

What am I missing?

....

More generally, @Parameter is back in 7.2.1-RC, but it's unclear to me
at least what the direction is for this.  Are we now looking to remove
these annotations again in a future (major) release, with the favoured
approach being the SimplifiedJson syntax?  However, @Parameter is not
marked as deprecated in the current RC.  I don't get a clear sense from
the docs which way this is going (or indeed where it exactly is now).

I'd agree with Gary's sentiment from JUNEAU-85 that 7.1 -> 7.x should be
a non-breaking change, but it is the case that having multiple
concurrently valid techniques is confusing at present (at least to me);
this could be a documentation fix though.

Thanks

David