Re: [DISCUSS] Swagger UI 3.0

[Francesco Chicchiriccò <il...@apache.org>]

FYI: https://issues.apache.org/jira/browse/SYNCOPE-1262

On 26/12/2017 17:27, Francesco Chicchiriccò wrote:
> 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/