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/
