In Swagger UI parameter content type is not aligned with Schema and Model Schema

[stefanomorson]

In REST APIs SwaggerUI documentation sometimes the parameter content type is set to "application/xml" whereas the Model Schema is in JSON format.

Testflow:

• Open SwaggerUI
• Authenticate in kapua-sys as kapua-sy
• Copy the auth token in the box on the upper right corner of the page
• Open accounts POST
• Look at the parameter named "body"

The parameter content type is "application/xml" for the whereas the Model Schema is in JSON format

Expected:
The parameter content type and the Model Schema format have to be aligned respect to the data format

List of resources where the issue have been observed:

• Accounts
• Users
• Credentials
• Data Channels
• Data Clients
• Data Messages
• Data Metrics
• Device Connections
• Devices
• Domains
• Groups
• Roles
• Streams
• Tags

[stefanomorson]

As verifed by @lorthirk, the observed behaviour is due to a bug in swagger UI. We are currently using swagger ui version 2.1.4. The issue is solved by using a more recent version (2.1.5+).

[stefanomorson]

Additional activity (besides filing the CQ). Swagger UI contains dependencies from other projetcs that we have to CQ separately. In order to be able to use the swagger-ui artifacts from maven central we sholud check that the 3rd party content in the lib dir are a subset of the separately-filed CQs.

[stefanomorson]

Swagger-UI is valuable to improve the documentation and the usability of Kpua API. Kapua is currently on Swagger UI 2.1.4. Version 2.1.5 would resolve the bug but swagger ui project has now reached version 3.9.0. Initially we sticked with the 2.1.4 because a CQ was already available. Having to ask for a new CQ it worths to move to the latest release. Unfortunately the new release has plenty of new dependencies form js libraries.

according to @lorthirk:

The proposal is to change the way how the Swagger-UI is managed in Kapua. The idea is to let kapua just generate the JSON file that swagger reads to generate the API UI. This can be done by just using the swagger java API to annotate the classes. Then the Swagger UI will be provided by a separated component that can be run in a docker container. By doing so:

• Swagger UI will become a works-with dependency, that should be much easier from an IP process point of view.
• We can remove a bit of non-core code from Kapua.

[lorthirk]

A proposal can be found at https://github.com/lorthirk/kapua/tree/feature-update_swagger

[stefanomorson]

Maybe with the new configuration there's no works-with dependency at all. I dropped an email to emo to double check.