juneau-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Goddard <godd...@acm.org>
Subject Swagger in RestMethod (7.2.0 -> 7.2.1 and onwards)
Date Thu, 25 Oct 2018 18:32:09 GMT
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



Mime
View raw message