cxf-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "J. Fiala (JIRA)" <j...@apache.org>
Subject [jira] [Comment Edited] (CXF-6965) CXF Swagger2Feature does not correctly support QueryParam("") and DataHandler
Date Sat, 09 Jul 2016 14:55:11 GMT

    [ 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)

Mime
View raw message