You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@syncope.apache.org by Francesco Chicchiriccò <il...@apache.org> on 2017/12/26 16:27:28 UTC
[DISCUSS] Swagger UI 3.0
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/
Re: [DISCUSS] Swagger UI 3.0
Posted by 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/