syncope-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Francesco Chicchiriccò <ilgro...@apache.org>
Subject [DISCUSS] Swagger UI 3.0
Date Tue, 26 Dec 2017 16:27:28 GMT
Hi all,
since we introduced the support for Swagger (as an extension [1] - see 
it at at work [2]), I believe many have found it very useful.

We are currently shipping a patched version of Swagger UI 2.0 (backed by 
Swagger Core 1.5) [3], with JS support manually enabled for Matrix 
parameters - as such parameters are not officially supported by Swagger 
UI 2.0.

Luckily, after long discussions [4], it seems that Matrix parameters 
eventually found their way through the OpenAPI specification, and 
Swagger UI 3.0.

In order to profit from this, we need to generate an OpenAPI 3.0- 
compliant descriptor, as the current /rest/swagger.json is at 2.0 but, 
due to the presence of matrix parameters, doesn't load with Swagger UI 3.0.

There is an ongoing effort in CXF [5] to provide full support for 
OpenAPI 3.0, so I think we won't need to wait long to reach up to this 
point.
For the moment I have locally tested [6] (it requires CXF 
3.1.15-SNAPSHOT for our 2_0_X branch): it seems to work but:

 1. with SwaggerToOpenApiConversionFilter registered, /rest/openapi.json
    is generated but /rest/swagger.json returns an empty response
 2. openapi.json generates incorrect "servers" element, as swagger.json
    does not currently include host name
 3. while it seems that Swagger UI 3.0 loads it correctly, the browser's
    console shows several errors

The results of such test are available at [7] - you can check by 
yourself by loading it into http://petstore.swagger.io/

FYI, I have just solved some Swagger warnings with commits [8][9], to 
better prepare the upgrade to Swagger UI 3.0.

Thoughts?
Regards.

[1] https://syncope.apache.org/docs/reference-guide.html#swagger
[2] http://syncope-vm.apache.org:9080/syncope/swagger/
[3] https://github.com/apache/syncope/tree/2_0_X/ext/swagger-ui
[4] https://github.com/OAI/OpenAPI-Specification/issues/69
[5] https://issues.apache.org/jira/browse/CXF-7525
[6] 
https://cwiki.apache.org/confluence/display/CXF20DOC/Swagger2Feature#Swagger2Feature-ConvertingtoOpenAPIJSON
[7] http://rovere.tirasa.net/~ilgrosso/new.json
[8] 
https://github.com/apache/syncope/commit/130c4a084710b77eb7005bf0885cfccaa5d39558
[9] 
https://github.com/apache/syncope/commit/75ee922abd7072ef1d87824e1388eaa5facfcd04

-- 
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Member at The Apache Software Foundation
Syncope, Cocoon, Olingo, CXF, OpenJPA, PonyMail
http://home.apache.org/~ilgrosso/


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message