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:[email protected]] > Sent: Freitag, 9. Oktober 2015 13:31 > To: [email protected] > 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/
