[
https://issues.apache.org/jira/browse/OPENMEETINGS-2667?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Sebastian Wagner updated OPENMEETINGS-2667:
-------------------------------------------
Description:
This ticket addresses 2 items
h1. Wrapping response generated schema into Root element
The way how CXF generates the JSON a response looks like this:
{code:java}
{
"serviceResult": {
"message": "9f51e7d6-e662-463a-b410-7bf31357f111",
"type": "SUCCESS"
}
}
{code}
It wraps it into a "serviceResult", while that part is not really part of the
schema.
Based on our API definition it would expect:
{code:java}
{
"message": "9f51e7d6-e662-463a-b410-7bf31357f111",
"type": "SUCCESS"
}
{code}
=> no wrapping into a "serviceResult": \{ ... }
There is a way to turn off this generation of wrapping / root elements in CXF.
But that would break existing clients.
So the challenge is to generate an API definition that actually matches the
response.
The only way to generate the correct documentation seems to be to wrap the
schema class into a wrapper object so that the schema matches the generated
json response and have that wrapper as meta information for the
swagger.annotation to the swagger annotation.
It would be better to drop the root / wrapping element on the long run in CXF.
But that would be a breaking change to the API and probably require a new
version.
h1. Providing Example responses
There isn't a possibility to provide example responses at the moment.
Also it might be better to generate those into separated classes so that the
API class won't get too large to read.
was:
This ticket addresses 2 items
h1. Wrapping response generated schema into Root element
The way how CXF generates the JSON a response looks like this:
{code:java}
{
"serviceResult": {
"message": "9f51e7d6-e662-463a-b410-7bf31357f111",
"type": "SUCCESS"
}
}
{code}
It wraps it into a "serviceResult", while that part is not really part of the
schema.
Based on our API definition it would expect:
{code:java}
{
"message": "9f51e7d6-e662-463a-b410-7bf31357f111",
"type": "SUCCESS"
}
{code}
=> no wrapping into a "serviceResult": \{ ... }
There is a way to turn off this generation of wrapping / root elements in CXF.
But that would break existing clients.
So the challenge is to generate an API definition that actually matches the
response.
The only way to generate the correct documentation seems to be to wrap the
schema class into a wrapper object so that the schema matches the generated and
only supply that to the swagger annotation.
Its not super nice. But it works for now. It would be better to drop the root /
wrapping element on the long run. But that would be a breaking change to the
API and probably require a new version.
h1. Providing Example responses
There isn't a possibility to provide example responses. Also it might be better
to generate those into separated classes so that the API class won't get too
large to read through
> Generated swagger has incorrect response, missing root element in schema and
> provide example responses
> ------------------------------------------------------------------------------------------------------
>
> Key: OPENMEETINGS-2667
> URL: https://issues.apache.org/jira/browse/OPENMEETINGS-2667
> Project: Openmeetings
> Issue Type: Improvement
> Components: Documentation, SOAP/REST API
> Affects Versions: 7.0.0
> Reporter: Sebastian Wagner
> Assignee: Sebastian Wagner
> Priority: Major
> Fix For: 7.0.0
>
>
> This ticket addresses 2 items
> h1. Wrapping response generated schema into Root element
> The way how CXF generates the JSON a response looks like this:
> {code:java}
> {
> "serviceResult": {
> "message": "9f51e7d6-e662-463a-b410-7bf31357f111",
> "type": "SUCCESS"
> }
> }
> {code}
> It wraps it into a "serviceResult", while that part is not really part of the
> schema.
> Based on our API definition it would expect:
> {code:java}
> {
> "message": "9f51e7d6-e662-463a-b410-7bf31357f111",
> "type": "SUCCESS"
> }
> {code}
> => no wrapping into a "serviceResult": \{ ... }
> There is a way to turn off this generation of wrapping / root elements in
> CXF. But that would break existing clients.
> So the challenge is to generate an API definition that actually matches the
> response.
> The only way to generate the correct documentation seems to be to wrap the
> schema class into a wrapper object so that the schema matches the generated
> json response and have that wrapper as meta information for the
> swagger.annotation to the swagger annotation.
> It would be better to drop the root / wrapping element on the long run in
> CXF. But that would be a breaking change to the API and probably require a
> new version.
> h1. Providing Example responses
> There isn't a possibility to provide example responses at the moment.
> Also it might be better to generate those into separated classes so that the
> API class won't get too large to read.
>
>
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
