From dev-return-1904-apmail-juneau-dev-archive=juneau.apache.org@juneau.apache.org Thu Oct 25 20:53:00 2018 Return-Path: X-Original-To: apmail-juneau-dev-archive@minotaur.apache.org Delivered-To: apmail-juneau-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5391F1891F for ; Thu, 25 Oct 2018 20:53:00 +0000 (UTC) Received: (qmail 44978 invoked by uid 500); 25 Oct 2018 20:53:00 -0000 Delivered-To: apmail-juneau-dev-archive@juneau.apache.org Received: (qmail 44941 invoked by uid 500); 25 Oct 2018 20:53:00 -0000 Mailing-List: contact dev-help@juneau.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.apache.org Delivered-To: mailing list dev@juneau.apache.org Received: (qmail 44930 invoked by uid 99); 25 Oct 2018 20:52:59 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 25 Oct 2018 20:52:59 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 1DE26185A8D for ; Thu, 25 Oct 2018 20:52:59 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 1.889 X-Spam-Level: * X-Spam-Status: No, score=1.889 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=2, RCVD_IN_DNSWL_NONE=-0.0001, SPF_PASS=-0.001, T_DKIMWL_WL_MED=-0.01] autolearn=disabled Authentication-Results: spamd3-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id WNEeaZ1sQTS3 for ; Thu, 25 Oct 2018 20:52:56 +0000 (UTC) Received: from mail-qt1-f169.google.com (mail-qt1-f169.google.com [209.85.160.169]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTPS id 11CD35F33E for ; Thu, 25 Oct 2018 20:52:56 +0000 (UTC) Received: by mail-qt1-f169.google.com with SMTP id a10-v6so11632864qtp.2 for ; Thu, 25 Oct 2018 13:52:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=WaOdKUOnK04SLfA6f0hQRsbSboB8yAMJYT20/VTkbDw=; b=PL6fYdHCsIIGhL3n6X06SbtZDXQsmt7Om7AgBlHTqNPs6N15aGg5ZmNgQ9DIH4NcUw w0vnYyt99LeO34VVWIrG/uZERZcg/+GaAnuJ/B2K9YYy2vHIx1yeK32sSEeJ8xHcqyUK /g+S6k2bYoNEnY3yt41NDutmyVYpHlvorKj6dHQi+CoxYYpH8d+znoZOPOZGUrcuz2kc HV/yMFjvqlhci6ZHh4Lkqk/04DcJOhQ4fqomp/7BWz9gfB/OWYwsuMX5qE/7g5t3WIYa tKiTB/oUZ5at9KAHGMkbXA+K/k7fKaHGnBHF9oIuvfYYGbBQ52kPyHtWKuic0l42ZnAf Yo+w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=WaOdKUOnK04SLfA6f0hQRsbSboB8yAMJYT20/VTkbDw=; b=cZOvO8a85kQYqzh3ELr6Q6Z6dRSCx3F+aDlRML+WAf8eBEnHMYFBnH5xjZHnwm7rWG crWcaA7krB5gJBDP5/9McJ7dOQ6+gqOaC0s0s/edztjUQh+qHKA/XqynTWQuMXSdmqrS w1zD4IO37KeMeMZLLOhYGJShORIi6a62+t6JJoC1yzhXFaiCK9cU/6c7zHYEEpy+JxAE msh9xksUrIt5iJnyiFD+RCRn2p1IvjtvzwBWgCXBlh27tb/xeU5S5wND3KArVi5WgIxc ZnZjkI8yBVz0Un+WZW2GuBgEOyS3wNUY89TK2tTD8YJxirKkNa+Ei2iFkiKmcNBAxC4r fKaA== X-Gm-Message-State: AGRZ1gIjUSw3Gu/wqsYvMDxxNcvYtctbVhD/HxmMci4bz6dL1yNDynjf 4ZxYgBkwrf4TsCuKDhbX49dpJnG6OJWWcjEfvOw4+M39 X-Google-Smtp-Source: AJdET5ciP16NzyTivgGeZc+5419+3Oqii2vzLmGnAxsfXPmyjGG7CsQUZv6DV8DmRm5jpaUfJ5Lo81PxT4u1oOt7jSw= X-Received: by 2002:a0c:acaf:: with SMTP id m44mr789153qvc.142.1540500774623; Thu, 25 Oct 2018 13:52:54 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: James Bognar Date: Thu, 25 Oct 2018 16:52:18 -0400 Message-ID: Subject: Re: Swagger in RestMethod (7.2.0 -> 7.2.1 and onwards) To: dev@juneau.apache.org Content-Type: multipart/alternative; boundary="000000000000729d90057913c9a4" --000000000000729d90057913c9a4 Content-Type: text/plain; charset="UTF-8" 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 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 > > > --000000000000729d90057913c9a4 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi David,

I could use some guidance her= e actually on whether to keep the=C2=A0@Parameter annotation.=C2=A0 The pla= n 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:=C2=A0=C2=A0

@RestMethod(= name=3D"GET",
=C2=A0 =C2=A0 path=3D"/foo/{somePathParam}/= *",
=C2=A0 =C2=A0 properties =3D{
=C2=A0 =C2=A0 =C2=A0 =C2=A0 @P= roperty(name=3DHTMLDOC_header, value=3D"$L{title}")
=C2=A0 =C2= =A0 }
)
public ServiceResult someMethod(
=C2= =A0 =C2=A0 =C2=A0 =C2=A0 RestRequest request,
=C2=A0 =C2=A0 =C2=A0 =C2= =A0 RestResponse response,
=C2=A0 =C2=A0 =C2=A0 =C2=A0 @Path(
= =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 name=3D"somePathParam",=
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 description=3D"xx= x"
=C2=A0 =C2=A0 =C2=A0 =C2=A0 )
=C2=A0 =C2=A0 =C2= =A0 =C2=A0 String somePathParam) {
=C2=A0 =C2=A0 =C2=A0 =C2=A0...
=C2= =A0 =C2=A0}

The=C2=A0@MethodSwagger(parameters) annotatio= n is thus really not needed anymore, but the Simplified-JSON syntax for def= ining it is provided as a free-form way of doing so.=C2=A0 The=C2=A0@Parame= ter 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 para= meters in the=C2=A0@MethodSwagger like so:

@RestMe= thod(name=3D"GET",
=C2=A0 =C2=A0 swagger=3D@MethodSwagger(
= =C2=A0 =C2=A0 =C2=A0 =C2=A0 parameters=3D{
=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 "{name:'somePathParam',in:'path',descrip= tion:'xxx'}"
=C2=A0 =C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0= )
)

However, parameters defined like this = are considered "documentation only", meaning you don't get au= to-validation of parameter values.=C2=A0 That's actually part of the de= sign because it allows you to provide either validating or non-validating S= wagger.=C2=A0 For example,=C2=A0

// Validating
@Path(
=C2=A0 =C2=A0 name=3D"somePathParam"= ,
=C2=A0 =C2=A0 description=3D"xxx",
=C2=A0 = =C2=A0 minLength=3D10, maxLength=3D20
)

= // Non-validating
@RestMethod(name=3D"GET",
=C2=A0 =C2=A0= swagger=3D@MethodSwagger(
=C2=A0 =C2=A0 =C2=A0 =C2=A0 parameters=3D{=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 "{name:'somePathParam&#= 39;,in:'path',description:'xxx',minLength:10,maxLength:20}&= quot;
=C2=A0 =C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 )
)

As far as keepin= g=C2=A0@Parameter, I could re-add it using a separate "parameters2&quo= t; attribute like so:
@RestMethod(name=3D"GET"= ,
=C2=A0 =C2=A0 swagger=3D@MethodSwagger(
=C2=A0 =C2=A0 =C2=A0 =C2=A0= parameters2=3D{
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 @Parameter(....)
=C2= =A0 =C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 )
)

My concerns with that though are that we're defining two separ= ate ways of defining free-form parameters.=C2=A0 And the existing=C2=A0@Par= ameter annotation didn't get the Swagger spec exactly correct (it was a= n amalgam of "body" and the other parameter types which only has = some overlap in Swagger).=C2=A0

I'm not sure w= hy you're seeing that "@Path used without name or value" erro= r.=C2=A0 I'll see if I can reproduce that.=C2=A0 The workaround is to a= dd the name of your path parameter like so:

public Servi= ceResult someMethod(
=C2=A0 =C2=A0 RestRequest request,
=C2=A0= =C2=A0 RestResponse response,
=C2=A0 =C2=A0 @Path("somePathParam&q= uot;) String somePathParam) {
=C2=A0 =C2=A0 =C2=A0 ...
=C2=A0 = =C2=A0}
=C2=A0

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 <= br> 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:

=C2=A0 =C2=A0swagger =3D @MethodSwagger(
=C2=A0 =C2=A0 =C2=A0parameters=3D {
=C2=A0 =C2=A0 =C2=A0 =C2=A0@Parameter(in=3D"path", name=3D"s= omePathParam", description=3D"xxx"),
=C2=A0 =C2=A0 =C2=A0}
=C2=A0 =C2=A0 ),

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
htt= p://juneau.apache.org/site/apidocs/org/apache/juneau/rest/annotation/RestMe= thod.html#swagger--,
which is of this format as per the docs:

=C2=A0 =C2=A0swagger=3D{
=C2=A0 =C2=A0 =C2=A0"parameters:[",
=C2=A0 =C2=A0 =C2=A0 =C2=A0"{name:'propertyName',in:'path&= #39;,description:'The system property
name.'},",
=C2=A0 =C2=A0 =C2=A0 =C2=A0"{in:'body',description:'The ne= w system property value.'}",
=C2=A0 =C2=A0 =C2=A0"],",
=C2=A0 =C2=A0 =C2=A0"responses:{",
=C2=A0 =C2=A0 =C2=A0 =C2=A0"302: {headers:{Location:{description:'= The root URL of this
resource.'}}},",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0"403: {description:'User is not = an admin.'}",
=C2=A0 =C2=A0 =C2=A0 "}"
=C2=A0 =C2=A0 }

So my method updates to something like this:

=C2=A0 =C2=A0@RestMethod(name=3D"GET", path=3D"/foo/{somePat= hParam}/*",
guards=3DFooGuard.class,
=C2=A0 =C2=A0 =C2=A0swagger =3D {
=C2=A0 =C2=A0 =C2=A0 =C2=A0"parameters:[",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0"{name:'somePathParam',in:&#= 39;path',description:'xxx',required:true}",
=C2=A0 =C2=A0 =C2=A0 =C2=A0"],"
=C2=A0 =C2=A0 =C2=A0},
=C2=A0 =C2=A0 =C2=A0properties =3D { // some props }
=C2=A0 =C2=A0)
=C2=A0 =C2=A0public ServiceResult someMethod(RestRequest request, RestRespo= nse
response, @Path String somePathParam) {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 // etc.
=C2=A0 =C2=A0}

However, this gives me a syntax error in Eclipse:

=C2=A0 =C2=A0Type mismatch: cannot convert from String[] to MethodSwagger
Any idea what I'm doing wrong here? (I am assuming I'm doing someth= ing
wrong)

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

=C2=A0 =C2=A0@RestMethod(name=3D"GET",
=C2=A0 =C2=A0 =C2=A0 =C2=A0path=3D"/foo/{somePathParam}/*",
=C2=A0 =C2=A0 =C2=A0 =C2=A0properties =3D{
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0@Property(name=3DHTMLDOC_header, value=3D= "$L{title}"),
=C2=A0 =C2=A0 =C2=A0 =C2=A0},
=C2=A0 =C2=A0 =C2=A0 =C2=A0swagger =3D @MethodSwagger(
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0parameters=3D {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 "{name:'somePathParam= 9;,in:'path',description:'xxx'}",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0}
=C2=A0 =C2=A0 =C2=A0 =C2=A0)
=C2=A0 =C2=A0)
=C2=A0 =C2=A0public ServiceResult someMethod(RestRequest request,
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0RestRe= sponse response,
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0@Path = String somePathParam) {
=C2=A0 =C2=A0 =C2=A0 =C2=A0return null; //(Not really)
=C2=A0 =C2=A0}

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)&#= 39;
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.=C2=A0 Are we now looking to remove=
these annotations again in a future (major) release, with the favoured
approach being the SimplifiedJson syntax?=C2=A0 However, @Parameter is not =
marked as deprecated in the current RC.=C2=A0 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 s= hould 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


--000000000000729d90057913c9a4--