About the Swagger feature (and an extension proposal)

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

About the Swagger feature (and an extension proposal)

ilgrosso
Hi all,
last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's talk
[1] and he briefly mentioned the new Swagger feature [2].

It looked great, so I wanted to add such feature as an optional Syncope
extension [3] and I've started playing with it.

I noticed that Swagger's SwaggerSerializers (used by Swagger2Feature)
was doing a great job in generating endpoint and schema information from
our (not Swagger-annotated) JAX-RS interface, but I was somehow
unsatisfied of the final result - as seen through Swagger UI - for a
couple of reasons:

1. all endpoints were falling under a single "default" dropdown, despite
of being defined in 25+ different @Path-annotated classes
2. being such services and methods documented exclusively via Javadoc, I
was hoping to get it as it can happen with WADL

For this reason I've developed an extension to original
SwaggerSerializers [4] (I also had to extend Swagger2Feature naturally [5]).

I am quite satisfied of the final result, which solves both issues
reported above; as you can see the code is in Syncope repository but it
is not related to anything specific about Syncope, so I was thinking if
it makes sense to refactor [4] and [5] as a patch for CXF.

WDYT?

[1]
http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8487ba3#.VheMR5cj1hE
[2] https://cxf.apache.org/docs/swagger2feature.html
[3] https://issues.apache.org/jira/browse/SYNCOPE-704
[4]
https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.java
[5]
https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java

--
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/


Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

Sergey Beryozkin
Administrator
Hi Francesco

Very nice - this is great that one can produce Swagger output without
having to introduce Swagger annotations (FYI Andriy Redko worked with a
Swagger team to improve Swagger JAXRS introspection).

Andrei Shakirin has a good point that JAX-RS annotations can not provide
the same amount of information as Swagger annotations can (ex: response
codes, authorization schemes) but the fact that your code is capable of
enriching the output with JavaDocs is a big plus - some of information
missing from JAX-RS annotations can def be documented in Java docs (ex -
a list of the possible response codes is only informative - not really
machine processable, etc).

Re grouping the same path methods under a unique root, IMHO it is a good
idea - easier to read, just may be we should make it configurable (in
Swagger2Feature), default is 'true', to make sure this auto-regrouping
does not affect the endpoints that do not require it for whatever reasons

Thanks, Sergey

On 09/10/15 11:00, Francesco Chicchiriccò wrote:

> Hi all,
> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's talk
> [1] and he briefly mentioned the new Swagger feature [2].
>
> It looked great, so I wanted to add such feature as an optional Syncope
> extension [3] and I've started playing with it.
>
> I noticed that Swagger's SwaggerSerializers (used by Swagger2Feature)
> was doing a great job in generating endpoint and schema information from
> our (not Swagger-annotated) JAX-RS interface, but I was somehow
> unsatisfied of the final result - as seen through Swagger UI - for a
> couple of reasons:
>
> 1. all endpoints were falling under a single "default" dropdown, despite
> of being defined in 25+ different @Path-annotated classes
> 2. being such services and methods documented exclusively via Javadoc, I
> was hoping to get it as it can happen with WADL
>
> For this reason I've developed an extension to original
> SwaggerSerializers [4] (I also had to extend Swagger2Feature naturally
> [5]).
>
> I am quite satisfied of the final result, which solves both issues
> reported above; as you can see the code is in Syncope repository but it
> is not related to anything specific about Syncope, so I was thinking if
> it makes sense to refactor [4] and [5] as a patch for CXF.
>
> WDYT?
>
> [1]
> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8487ba3#.VheMR5cj1hE
>
> [2] https://cxf.apache.org/docs/swagger2feature.html
> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
> [4]
> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.java
>
> [5]
> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java
>
>

Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

Sergey Beryozkin
Administrator
Yeah, I guess we just should make both options (re-grouping and
enriching with Java docs) configurable - so that it can co-exist with
the endpoints which do prefer setting Swagger annotations

Thanks, Sergey
On 09/10/15 11:26, Sergey Beryozkin wrote:

> Hi Francesco
>
> Very nice - this is great that one can produce Swagger output without
> having to introduce Swagger annotations (FYI Andriy Redko worked with a
> Swagger team to improve Swagger JAXRS introspection).
>
> Andrei Shakirin has a good point that JAX-RS annotations can not provide
> the same amount of information as Swagger annotations can (ex: response
> codes, authorization schemes) but the fact that your code is capable of
> enriching the output with JavaDocs is a big plus - some of information
> missing from JAX-RS annotations can def be documented in Java docs (ex -
> a list of the possible response codes is only informative - not really
> machine processable, etc).
>
> Re grouping the same path methods under a unique root, IMHO it is a good
> idea - easier to read, just may be we should make it configurable (in
> Swagger2Feature), default is 'true', to make sure this auto-regrouping
> does not affect the endpoints that do not require it for whatever reasons
>
> Thanks, Sergey
>
> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
>> Hi all,
>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's talk
>> [1] and he briefly mentioned the new Swagger feature [2].
>>
>> It looked great, so I wanted to add such feature as an optional Syncope
>> extension [3] and I've started playing with it.
>>
>> I noticed that Swagger's SwaggerSerializers (used by Swagger2Feature)
>> was doing a great job in generating endpoint and schema information from
>> our (not Swagger-annotated) JAX-RS interface, but I was somehow
>> unsatisfied of the final result - as seen through Swagger UI - for a
>> couple of reasons:
>>
>> 1. all endpoints were falling under a single "default" dropdown, despite
>> of being defined in 25+ different @Path-annotated classes
>> 2. being such services and methods documented exclusively via Javadoc, I
>> was hoping to get it as it can happen with WADL
>>
>> For this reason I've developed an extension to original
>> SwaggerSerializers [4] (I also had to extend Swagger2Feature naturally
>> [5]).
>>
>> I am quite satisfied of the final result, which solves both issues
>> reported above; as you can see the code is in Syncope repository but it
>> is not related to anything specific about Syncope, so I was thinking if
>> it makes sense to refactor [4] and [5] as a patch for CXF.
>>
>> WDYT?
>>
>> [1]
>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8487ba3#.VheMR5cj1hE
>>
>>
>> [2] https://cxf.apache.org/docs/swagger2feature.html
>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
>> [4]
>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.java
>>
>>
>> [5]
>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java
>>
>>
>>
>


--
Sergey Beryozkin

Talend Community Coders
http://coders.talend.com/
Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

Sergey Beryozkin
Administrator
It is already configurable, thanks.
I can also move DocumentationProvider to a .model. subpackage, to avoid
having references to .wadl. in Swagger features :-)

Cheers, Sergey
On 09/10/15 11:28, Sergey Beryozkin wrote:

> Yeah, I guess we just should make both options (re-grouping and
> enriching with Java docs) configurable - so that it can co-exist with
> the endpoints which do prefer setting Swagger annotations
>
> Thanks, Sergey
> On 09/10/15 11:26, Sergey Beryozkin wrote:
>> Hi Francesco
>>
>> Very nice - this is great that one can produce Swagger output without
>> having to introduce Swagger annotations (FYI Andriy Redko worked with a
>> Swagger team to improve Swagger JAXRS introspection).
>>
>> Andrei Shakirin has a good point that JAX-RS annotations can not provide
>> the same amount of information as Swagger annotations can (ex: response
>> codes, authorization schemes) but the fact that your code is capable of
>> enriching the output with JavaDocs is a big plus - some of information
>> missing from JAX-RS annotations can def be documented in Java docs (ex -
>> a list of the possible response codes is only informative - not really
>> machine processable, etc).
>>
>> Re grouping the same path methods under a unique root, IMHO it is a good
>> idea - easier to read, just may be we should make it configurable (in
>> Swagger2Feature), default is 'true', to make sure this auto-regrouping
>> does not affect the endpoints that do not require it for whatever reasons
>>
>> Thanks, Sergey
>>
>> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
>>> Hi all,
>>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's talk
>>> [1] and he briefly mentioned the new Swagger feature [2].
>>>
>>> It looked great, so I wanted to add such feature as an optional Syncope
>>> extension [3] and I've started playing with it.
>>>
>>> I noticed that Swagger's SwaggerSerializers (used by Swagger2Feature)
>>> was doing a great job in generating endpoint and schema information from
>>> our (not Swagger-annotated) JAX-RS interface, but I was somehow
>>> unsatisfied of the final result - as seen through Swagger UI - for a
>>> couple of reasons:
>>>
>>> 1. all endpoints were falling under a single "default" dropdown, despite
>>> of being defined in 25+ different @Path-annotated classes
>>> 2. being such services and methods documented exclusively via Javadoc, I
>>> was hoping to get it as it can happen with WADL
>>>
>>> For this reason I've developed an extension to original
>>> SwaggerSerializers [4] (I also had to extend Swagger2Feature naturally
>>> [5]).
>>>
>>> I am quite satisfied of the final result, which solves both issues
>>> reported above; as you can see the code is in Syncope repository but it
>>> is not related to anything specific about Syncope, so I was thinking if
>>> it makes sense to refactor [4] and [5] as a patch for CXF.
>>>
>>> WDYT?
>>>
>>> [1]
>>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8487ba3#.VheMR5cj1hE
>>>
>>>
>>>
>>> [2] https://cxf.apache.org/docs/swagger2feature.html
>>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
>>> [4]
>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.java
>>>
>>>
>>>
>>> [5]
>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java
>>>
>>>
>>>
>>>
>>
>
>


--
Sergey Beryozkin

Talend Community Coders
http://coders.talend.com/
Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

ilgrosso
I've created

https://issues.apache.org/jira/browse/CXF-6633

for discussion and providing PR.

Regards.

On 09/10/2015 12:35, Sergey Beryozkin wrote:

> It is already configurable, thanks.
> I can also move DocumentationProvider to a .model. subpackage, to
> avoid having references to .wadl. in Swagger features :-)
>
> Cheers, Sergey
> On 09/10/15 11:28, Sergey Beryozkin wrote:
>> Yeah, I guess we just should make both options (re-grouping and
>> enriching with Java docs) configurable - so that it can co-exist with
>> the endpoints which do prefer setting Swagger annotations
>>
>> Thanks, Sergey
>> On 09/10/15 11:26, Sergey Beryozkin wrote:
>>> Hi Francesco
>>>
>>> Very nice - this is great that one can produce Swagger output without
>>> having to introduce Swagger annotations (FYI Andriy Redko worked with a
>>> Swagger team to improve Swagger JAXRS introspection).
>>>
>>> Andrei Shakirin has a good point that JAX-RS annotations can not
>>> provide
>>> the same amount of information as Swagger annotations can (ex: response
>>> codes, authorization schemes) but the fact that your code is capable of
>>> enriching the output with JavaDocs is a big plus - some of information
>>> missing from JAX-RS annotations can def be documented in Java docs
>>> (ex -
>>> a list of the possible response codes is only informative - not really
>>> machine processable, etc).
>>>
>>> Re grouping the same path methods under a unique root, IMHO it is a
>>> good
>>> idea - easier to read, just may be we should make it configurable (in
>>> Swagger2Feature), default is 'true', to make sure this auto-regrouping
>>> does not affect the endpoints that do not require it for whatever
>>> reasons
>>>
>>> Thanks, Sergey
>>>
>>> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
>>>> Hi all,
>>>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's talk
>>>> [1] and he briefly mentioned the new Swagger feature [2].
>>>>
>>>> It looked great, so I wanted to add such feature as an optional
>>>> Syncope
>>>> extension [3] and I've started playing with it.
>>>>
>>>> I noticed that Swagger's SwaggerSerializers (used by Swagger2Feature)
>>>> was doing a great job in generating endpoint and schema information
>>>> from
>>>> our (not Swagger-annotated) JAX-RS interface, but I was somehow
>>>> unsatisfied of the final result - as seen through Swagger UI - for a
>>>> couple of reasons:
>>>>
>>>> 1. all endpoints were falling under a single "default" dropdown,
>>>> despite
>>>> of being defined in 25+ different @Path-annotated classes
>>>> 2. being such services and methods documented exclusively via
>>>> Javadoc, I
>>>> was hoping to get it as it can happen with WADL
>>>>
>>>> For this reason I've developed an extension to original
>>>> SwaggerSerializers [4] (I also had to extend Swagger2Feature naturally
>>>> [5]).
>>>>
>>>> I am quite satisfied of the final result, which solves both issues
>>>> reported above; as you can see the code is in Syncope repository
>>>> but it
>>>> is not related to anything specific about Syncope, so I was
>>>> thinking if
>>>> it makes sense to refactor [4] and [5] as a patch for CXF.
>>>>
>>>> WDYT?
>>>>
>>>> [1]
>>>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8487ba3#.VheMR5cj1hE 
>>>>
>>>> [2] https://cxf.apache.org/docs/swagger2feature.html
>>>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
>>>> [4]
>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.java 
>>>>
>>>> [5]
>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java 
>>>>

--
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/

Reply | Threaded
Open this post in threaded view
|

RE: About the Swagger feature (and an extension proposal)

Andrei Shakirin
Hi Francesco and Sergey,

We have discussed the topic with Sergei last days and I find Francesco proposal the most preferable at the moment.
From one side we can keep Swagger and WADL approaches not mixed.
From other side users can benefit from Swagger features even if they use WADL first of Java first JAX-RS service implementations.
+1 from my side.

@Francesco: thanks a lot for your proposal and contribution, I am really happy with that.

Regards,
Andrei.

> -----Original Message-----
> From: Francesco Chicchiriccò [mailto:[hidden email]]
> Sent: Freitag, 9. Oktober 2015 13:31
> To: [hidden email]
> Subject: Re: About the Swagger feature (and an extension proposal)
>
> I've created
>
> https://issues.apache.org/jira/browse/CXF-6633
>
> for discussion and providing PR.
>
> Regards.
>
> On 09/10/2015 12:35, Sergey Beryozkin wrote:
> > It is already configurable, thanks.
> > I can also move DocumentationProvider to a .model. subpackage, to
> > avoid having references to .wadl. in Swagger features :-)
> >
> > Cheers, Sergey
> > On 09/10/15 11:28, Sergey Beryozkin wrote:
> >> Yeah, I guess we just should make both options (re-grouping and
> >> enriching with Java docs) configurable - so that it can co-exist with
> >> the endpoints which do prefer setting Swagger annotations
> >>
> >> Thanks, Sergey
> >> On 09/10/15 11:26, Sergey Beryozkin wrote:
> >>> Hi Francesco
> >>>
> >>> Very nice - this is great that one can produce Swagger output
> >>> without having to introduce Swagger annotations (FYI Andriy Redko
> >>> worked with a Swagger team to improve Swagger JAXRS introspection).
> >>>
> >>> Andrei Shakirin has a good point that JAX-RS annotations can not
> >>> provide the same amount of information as Swagger annotations can
> >>> (ex: response codes, authorization schemes) but the fact that your
> >>> code is capable of enriching the output with JavaDocs is a big plus
> >>> - some of information missing from JAX-RS annotations can def be
> >>> documented in Java docs (ex - a list of the possible response codes
> >>> is only informative - not really machine processable, etc).
> >>>
> >>> Re grouping the same path methods under a unique root, IMHO it is a
> >>> good idea - easier to read, just may be we should make it
> >>> configurable (in Swagger2Feature), default is 'true', to make sure
> >>> this auto-regrouping does not affect the endpoints that do not
> >>> require it for whatever reasons
> >>>
> >>> Thanks, Sergey
> >>>
> >>> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
> >>>> Hi all,
> >>>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's
> >>>> talk [1] and he briefly mentioned the new Swagger feature [2].
> >>>>
> >>>> It looked great, so I wanted to add such feature as an optional
> >>>> Syncope extension [3] and I've started playing with it.
> >>>>
> >>>> I noticed that Swagger's SwaggerSerializers (used by
> >>>> Swagger2Feature) was doing a great job in generating endpoint and
> >>>> schema information from our (not Swagger-annotated) JAX-RS
> >>>> interface, but I was somehow unsatisfied of the final result - as
> >>>> seen through Swagger UI - for a couple of reasons:
> >>>>
> >>>> 1. all endpoints were falling under a single "default" dropdown,
> >>>> despite of being defined in 25+ different @Path-annotated classes
> >>>> 2. being such services and methods documented exclusively via
> >>>> Javadoc, I was hoping to get it as it can happen with WADL
> >>>>
> >>>> For this reason I've developed an extension to original
> >>>> SwaggerSerializers [4] (I also had to extend Swagger2Feature
> >>>> naturally [5]).
> >>>>
> >>>> I am quite satisfied of the final result, which solves both issues
> >>>> reported above; as you can see the code is in Syncope repository
> >>>> but it is not related to anything specific about Syncope, so I was
> >>>> thinking if it makes sense to refactor [4] and [5] as a patch for
> >>>> CXF.
> >>>>
> >>>> WDYT?
> >>>>
> >>>> [1]
> >>>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8
> >>>> 487ba3#.VheMR5cj1hE
> >>>>
> >>>> [2] https://cxf.apache.org/docs/swagger2feature.html
> >>>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
> >>>> [4]
> >>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
> >>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.j
> >>>> ava
> >>>>
> >>>> [5]
> >>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
> >>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java
> >>>>
>
> --
> Francesco Chicchiriccò
>
> Tirasa - Open Source Excellence
> http://www.tirasa.net/
>
> Involved at The Apache Software Foundation:
> member, Syncope PMC chair, Cocoon PMC, Olingo PMC
> http://people.apache.org/~ilgrosso/

Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

ilgrosso
On 09/10/2015 13:37, Andrei Shakirin wrote:
> Hi Francesco and Sergey,
>
> We have discussed the topic with Sergei last days and I find Francesco proposal the most preferable at the moment.
>  From one side we can keep Swagger and WADL approaches not mixed.
>  From other side users can benefit from Swagger features even if they use WADL first of Java first JAX-RS service implementations.
> +1 from my side.
>
> @Francesco: thanks a lot for your proposal and contribution, I am really happy with that.

Thanks Andrei: I am glad that my PR was accepted.
Naturally I've also dropped the original classes in Syncope and we're
using the updated CXF.

Regards.

>> -----Original Message-----
>> From: Francesco Chicchiriccò [mailto:[hidden email]]
>> Sent: Freitag, 9. Oktober 2015 13:31
>> To: [hidden email]
>> Subject: Re: About the Swagger feature (and an extension proposal)
>>
>> I've created
>>
>> https://issues.apache.org/jira/browse/CXF-6633
>>
>> for discussion and providing PR.
>>
>> Regards.
>>
>> On 09/10/2015 12:35, Sergey Beryozkin wrote:
>>> It is already configurable, thanks.
>>> I can also move DocumentationProvider to a .model. subpackage, to
>>> avoid having references to .wadl. in Swagger features :-)
>>>
>>> Cheers, Sergey
>>> On 09/10/15 11:28, Sergey Beryozkin wrote:
>>>> Yeah, I guess we just should make both options (re-grouping and
>>>> enriching with Java docs) configurable - so that it can co-exist with
>>>> the endpoints which do prefer setting Swagger annotations
>>>>
>>>> Thanks, Sergey
>>>> On 09/10/15 11:26, Sergey Beryozkin wrote:
>>>>> Hi Francesco
>>>>>
>>>>> Very nice - this is great that one can produce Swagger output
>>>>> without having to introduce Swagger annotations (FYI Andriy Redko
>>>>> worked with a Swagger team to improve Swagger JAXRS introspection).
>>>>>
>>>>> Andrei Shakirin has a good point that JAX-RS annotations can not
>>>>> provide the same amount of information as Swagger annotations can
>>>>> (ex: response codes, authorization schemes) but the fact that your
>>>>> code is capable of enriching the output with JavaDocs is a big plus
>>>>> - some of information missing from JAX-RS annotations can def be
>>>>> documented in Java docs (ex - a list of the possible response codes
>>>>> is only informative - not really machine processable, etc).
>>>>>
>>>>> Re grouping the same path methods under a unique root, IMHO it is a
>>>>> good idea - easier to read, just may be we should make it
>>>>> configurable (in Swagger2Feature), default is 'true', to make sure
>>>>> this auto-regrouping does not affect the endpoints that do not
>>>>> require it for whatever reasons
>>>>>
>>>>> Thanks, Sergey
>>>>>
>>>>> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
>>>>>> Hi all,
>>>>>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's
>>>>>> talk [1] and he briefly mentioned the new Swagger feature [2].
>>>>>>
>>>>>> It looked great, so I wanted to add such feature as an optional
>>>>>> Syncope extension [3] and I've started playing with it.
>>>>>>
>>>>>> I noticed that Swagger's SwaggerSerializers (used by
>>>>>> Swagger2Feature) was doing a great job in generating endpoint and
>>>>>> schema information from our (not Swagger-annotated) JAX-RS
>>>>>> interface, but I was somehow unsatisfied of the final result - as
>>>>>> seen through Swagger UI - for a couple of reasons:
>>>>>>
>>>>>> 1. all endpoints were falling under a single "default" dropdown,
>>>>>> despite of being defined in 25+ different @Path-annotated classes
>>>>>> 2. being such services and methods documented exclusively via
>>>>>> Javadoc, I was hoping to get it as it can happen with WADL
>>>>>>
>>>>>> For this reason I've developed an extension to original
>>>>>> SwaggerSerializers [4] (I also had to extend Swagger2Feature
>>>>>> naturally [5]).
>>>>>>
>>>>>> I am quite satisfied of the final result, which solves both issues
>>>>>> reported above; as you can see the code is in Syncope repository
>>>>>> but it is not related to anything specific about Syncope, so I was
>>>>>> thinking if it makes sense to refactor [4] and [5] as a patch for
>>>>>> CXF.
>>>>>>
>>>>>> WDYT?
>>>>>>
>>>>>> [1]
>>>>>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8
>>>>>> 487ba3#.VheMR5cj1hE
>>>>>>
>>>>>> [2] https://cxf.apache.org/docs/swagger2feature.html
>>>>>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
>>>>>> [4]
>>>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
>>>>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.j
>>>>>> ava
>>>>>>
>>>>>> [5]
>>>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
>>>>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java

--
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/

Reply | Threaded
Open this post in threaded view
|

Re: About the Swagger feature (and an extension proposal)

ilgrosso
FYI I've assembled a quick video showing the working integration of
Swagger UI and Syncope REST interface (powered by CXF) at

http://syncope.tirasa.net/news/apache-syncope-2.0.0-and-swagger.html

Regards.

On 09/10/2015 17:09, Francesco Chicchiriccò wrote:

> On 09/10/2015 13:37, Andrei Shakirin wrote:
>> Hi Francesco and Sergey,
>>
>> We have discussed the topic with Sergei last days and I find
>> Francesco proposal the most preferable at the moment.
>>  From one side we can keep Swagger and WADL approaches not mixed.
>>  From other side users can benefit from Swagger features even if they
>> use WADL first of Java first JAX-RS service implementations.
>> +1 from my side.
>>
>> @Francesco: thanks a lot for your proposal and contribution, I am
>> really happy with that.
>
> Thanks Andrei: I am glad that my PR was accepted.
> Naturally I've also dropped the original classes in Syncope and we're
> using the updated CXF.
>
> Regards.
>
>>> -----Original Message-----
>>> From: Francesco Chicchiriccò [mailto:[hidden email]]
>>> Sent: Freitag, 9. Oktober 2015 13:31
>>> To: [hidden email]
>>> Subject: Re: About the Swagger feature (and an extension proposal)
>>>
>>> I've created
>>>
>>> https://issues.apache.org/jira/browse/CXF-6633
>>>
>>> for discussion and providing PR.
>>>
>>> Regards.
>>>
>>> On 09/10/2015 12:35, Sergey Beryozkin wrote:
>>>> It is already configurable, thanks.
>>>> I can also move DocumentationProvider to a .model. subpackage, to
>>>> avoid having references to .wadl. in Swagger features :-)
>>>>
>>>> Cheers, Sergey
>>>> On 09/10/15 11:28, Sergey Beryozkin wrote:
>>>>> Yeah, I guess we just should make both options (re-grouping and
>>>>> enriching with Java docs) configurable - so that it can co-exist with
>>>>> the endpoints which do prefer setting Swagger annotations
>>>>>
>>>>> Thanks, Sergey
>>>>> On 09/10/15 11:26, Sergey Beryozkin wrote:
>>>>>> Hi Francesco
>>>>>>
>>>>>> Very nice - this is great that one can produce Swagger output
>>>>>> without having to introduce Swagger annotations (FYI Andriy Redko
>>>>>> worked with a Swagger team to improve Swagger JAXRS introspection).
>>>>>>
>>>>>> Andrei Shakirin has a good point that JAX-RS annotations can not
>>>>>> provide the same amount of information as Swagger annotations can
>>>>>> (ex: response codes, authorization schemes) but the fact that your
>>>>>> code is capable of enriching the output with JavaDocs is a big plus
>>>>>> - some of information missing from JAX-RS annotations can def be
>>>>>> documented in Java docs (ex - a list of the possible response codes
>>>>>> is only informative - not really machine processable, etc).
>>>>>>
>>>>>> Re grouping the same path methods under a unique root, IMHO it is a
>>>>>> good idea - easier to read, just may be we should make it
>>>>>> configurable (in Swagger2Feature), default is 'true', to make sure
>>>>>> this auto-regrouping does not affect the endpoints that do not
>>>>>> require it for whatever reasons
>>>>>>
>>>>>> Thanks, Sergey
>>>>>>
>>>>>> On 09/10/15 11:00, Francesco Chicchiriccò wrote:
>>>>>>> Hi all,
>>>>>>> last week at ApacheCon: Core EU 2015 I attended Andrei Shakirin's
>>>>>>> talk [1] and he briefly mentioned the new Swagger feature [2].
>>>>>>>
>>>>>>> It looked great, so I wanted to add such feature as an optional
>>>>>>> Syncope extension [3] and I've started playing with it.
>>>>>>>
>>>>>>> I noticed that Swagger's SwaggerSerializers (used by
>>>>>>> Swagger2Feature) was doing a great job in generating endpoint and
>>>>>>> schema information from our (not Swagger-annotated) JAX-RS
>>>>>>> interface, but I was somehow unsatisfied of the final result - as
>>>>>>> seen through Swagger UI - for a couple of reasons:
>>>>>>>
>>>>>>> 1. all endpoints were falling under a single "default" dropdown,
>>>>>>> despite of being defined in 25+ different @Path-annotated classes
>>>>>>> 2. being such services and methods documented exclusively via
>>>>>>> Javadoc, I was hoping to get it as it can happen with WADL
>>>>>>>
>>>>>>> For this reason I've developed an extension to original
>>>>>>> SwaggerSerializers [4] (I also had to extend Swagger2Feature
>>>>>>> naturally [5]).
>>>>>>>
>>>>>>> I am quite satisfied of the final result, which solves both issues
>>>>>>> reported above; as you can see the code is in Syncope repository
>>>>>>> but it is not related to anything specific about Syncope, so I was
>>>>>>> thinking if it makes sense to refactor [4] and [5] as a patch for
>>>>>>> CXF.
>>>>>>>
>>>>>>> WDYT?
>>>>>>>
>>>>>>> [1]
>>>>>>> http://apacheconcore2015.sched.org/event/1b440fe7cfe61985dc5aacf6f8
>>>>>>> 487ba3#.VheMR5cj1hE
>>>>>>>
>>>>>>> [2] https://cxf.apache.org/docs/swagger2feature.html
>>>>>>> [3] https://issues.apache.org/jira/browse/SYNCOPE-704
>>>>>>> [4]
>>>>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
>>>>>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwaggerSerializers.j
>>>>>>> ava
>>>>>>> [5]
>>>>>>> https://github.com/apache/syncope/blob/master/core/rest-cxf/src/mai
>>>>>>> n/java/org/apache/syncope/core/rest/cxf/SyncopeSwagger2Feature.java

--
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/