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 Fri, 09 Oct 2015 11:30:36 GMT
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/


Mime
View raw message