[
https://issues.apache.org/jira/browse/CXF-6965?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15369088#comment-15369088
]
J. Fiala edited comment on CXF-6965 at 7/9/16 2:54 PM:
-------------------------------------------------------
h2. Overview of issues with Swagger-API rendering
1. Nested parameters - @QueryParam not supported in Swagger
2. DataHandler - not supported in Swagger (rendered as Model instead type:file)
3. ApiParam example not rendered in Swagger
4. No polymorphism supported (Feature)
5. Enumeration values are always rendered inline as opposed to a separate
definition (Feature)
h3. 1. Example for nested parameters @QueryParam("") not supported in Swagger:
{code}
@Api(value = "/myService", description = "My Service")
public interface MyService {
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/hello")
public void hello(@QueryParam("")MyQueryParams params);
}
public class MyQueryParams {
String param1;
String param2;
//....
}
{code}
will render in WADL (CORRECT):
{code}
<resource path="/hello">
<method name="POST">
<request>
<param name="param2" style="query" type="xs:string"/>
<param name="param1" style="query" type="xs:string"/>
</request>
{code}
and in Swagger (WRONG - nested parameters not picked up):
{code}
"/myService/hello": {
"post": {
"tags": [
"myService"
],
"operationId": "hello",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "",
"in": "query",
"required": false,
"type": "string"
}
],
{code}
h3. 2. Example for DataHandler not supported in Swagger:
{code}
@Consumes({ MediaType.MULTIPART_FORM_DATA })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/helloMultipart")
public void helloMultipart(@Multipart(value= "payload" ,
type=MediaType.APPLICATION_OCTET_STREAM) DataHandler handler);
{code}
will render in Swagger with reference to definitions DataHandler instead of
type=file:
{code}
"/myService/helloMultipart": {
"post": {
"tags": [
"myService"
],
"operationId": "helloMultipart",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/DataHandler"
}
}
],
{code}
It will also add the definitions for DataHandler, DataSource, DataFlavour,
InputStream, CommandInfo, Outputstream, which makes no sense in the Swagger
file.
This would be the correct rendering (type=file)
{code}
{
"name": "payload",
"in": "formData",
"description": "",
"required": false,
"type": "file"
}
{code}
h3. 3. ApiParam example not rendered in Swagger
{code}
/**
* Swagger2Feature does not pick up example value
*
* @param myparam
*/
public void helloParameterExampleValue(@ApiParam(value="myparam",
example="hello my parameter") String myparam);
{code}
will currently become in Swagger definition (missing example):
{code}
"/myService/helloParameterExampleValue": {
"post": {
"tags": [
"myService"
],
"operationId": "helloParameterExampleValue",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "myparam",
"required": false,
"schema": {
"type": "string"
}
}
],
...
{code}
"example": "hello my parameter" should be rendered as well.
h3. 4. No polymorphism - inheritance supported (Feature)
Currently the Swagger2Feature doesn't support inheritance (WadlGenerator does!)
h3. 5. Enumeration values are always rendered inline as opposed to a separate
definition (Feature)
{code}
@Api(value = "/myService", description = "My Service")
public interface MyService {
@Consumes({ MediaType.MULTIPART_FORM_DATA })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/helloEnum")
public void helloEnum(MyBodyParams bodyParams);
}
@XmlRootElement(namespace="http://sample.com/myservice";)
public class MyBodyParams {
SampleEnum myEnum;
public SampleEnum getMyEnum() {
return myEnum;
}
public void setMyEnum(SampleEnum myEnum) {
this.myEnum = myEnum;
}
}
public enum SampleEnum {
draft, published, deleted;
}
{code}
will render as
{code}
"MyBodyParams": {
"type": "object",
"properties": {
"myEnum": {
"type": "string",
"enum": [
"draft",
"published",
"deleted"
]
}
}
},
{code}
it would be great to have it rendered as a definition instead
(https://github.com/OAI/OpenAPI-Specification/issues/300#issuecomment-77669429).
was (Author: jfx):
h2. Overview of issues with Swagger-API rendering
1. Nested parameters - @QueryParam not supported in Swagger
2. DataHandler - not supported in Swagger (rendered as Model instead type:file)
3. ApiParam example not rendered in Swagger
4. No polymorphism supported (Feature)
5. Enumeration values are always rendered inline as opposed to a separate
definition (Feature)
h3. 1. Example for nested parameters @QueryParam("") not supported in Swagger:
{code}
@Api(value = "/myService", description = "My Service")
public interface MyService {
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/hello")
public void hello(@QueryParam("")MyQueryParams params);
}
public class MyQueryParams {
String param1;
String param2;
//....
}
{code}
will render in WADL (CORRECT):
{code}
<resource path="/hello">
<method name="POST">
<request>
<param name="param2" style="query" type="xs:string"/>
<param name="param1" style="query" type="xs:string"/>
</request>
{code}
and in Swagger (WRONG - nested parameters not picked up):
{code}
"/myService/hello": {
"post": {
"tags": [
"myService"
],
"operationId": "hello",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "",
"in": "query",
"required": false,
"type": "string"
}
],
{code}
h3. 2. Example for DataHandler not supported in Swagger:
{code}
@Consumes({ MediaType.MULTIPART_FORM_DATA })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/helloMultipart")
public void helloMultipart(@Multipart(value= "payload" ,
type=MediaType.APPLICATION_OCTET_STREAM) DataHandler handler);
{code}
will render in Swagger with reference to definitions DataHandler instead of
type=file:
{code}
"/myService/helloMultipart": {
"post": {
"tags": [
"myService"
],
"operationId": "helloMultipart",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/DataHandler"
}
}
],
{code}
It will also add the definitions for DataHandler, DataSource, DataFlavour,
InputStream, CommandInfo, Outputstream, which makes no sense in the Swagger
file.
This would be the correct rendering (type=file)
{code}
{
"name": "payload",
"in": "formData",
"description": "",
"required": false,
"type": "file"
}
{code}
h3. 3. ApiParam example not rendered in Swagger
{code}
/**
* Swagger2Feature does not pick up example value
*
* @param myparam
*/
public void helloParameterExampleValue(@ApiParam(value="myparam",
example="hello my parameter") String myparam);
{code}
will currently become in Swagger definition (missing example):
{code}
"/myService/helloParameterExampleValue": {
"post": {
"tags": [
"myService"
],
"operationId": "helloParameterExampleValue",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "myparam",
"required": false,
"schema": {
"type": "string"
}
}
],
...
{code}
"example": "hello my parameter" should be rendered as well.
h3. 4. No polymorphism - inheritance supported
Currently the Swagger2Feature doesn't support inheritance (WadlGenerator does!)
h3. 5. Enumeration values are always rendered inline as opposed to a separate
definition (Feature)
{code}
@Api(value = "/myService", description = "My Service")
public interface MyService {
@Consumes({ MediaType.MULTIPART_FORM_DATA })
@Produces({ MediaType.APPLICATION_JSON })
@POST
@Path("/helloEnum")
public void helloEnum(MyBodyParams bodyParams);
}
@XmlRootElement(namespace="http://sample.com/myservice";)
public class MyBodyParams {
SampleEnum myEnum;
public SampleEnum getMyEnum() {
return myEnum;
}
public void setMyEnum(SampleEnum myEnum) {
this.myEnum = myEnum;
}
}
public enum SampleEnum {
draft, published, deleted;
}
{code}
will render as
{code}
"MyBodyParams": {
"type": "object",
"properties": {
"myEnum": {
"type": "string",
"enum": [
"draft",
"published",
"deleted"
]
}
}
},
{code}
it would be great to have it rendered as a definition instead
(https://github.com/OAI/OpenAPI-Specification/issues/300#issuecomment-77669429)
> CXF Swagger2Feature does not correctly support QueryParam("") and DataHandler
> -----------------------------------------------------------------------------
>
> Key: CXF-6965
> URL: https://issues.apache.org/jira/browse/CXF-6965
> Project: CXF
> Issue Type: Bug
> Components: JAX-RS
> Reporter: Sergey Beryozkin
> Priority: Minor
> Fix For: 3.2.0, 3.1.8
>
>
> See
> https://github.com/swagger-api/swagger-codegen/issues/2017#issuecomment-230426728
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
