cxf-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Francesco Chicchiriccò <ilgro...@apache.org>
Subject Re: About the Swagger feature (and an extension proposal)
Date Tue, 13 Oct 2015 06:27:40 GMT
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:ilgrosso@apache.org]
>>> Sent: Freitag, 9. Oktober 2015 13:31
>>> To: users@cxf.apache.org
>>> 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/


Mime
View raw message