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:[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/
