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/
