cancel
Showing results for 
Search instead for 
Did you mean: 

How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

SOLVED
Highlighted
Occasional Contributor

How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

I'm using the swagger-maven-plugin in a Java application with an old school servlet implementation. I'm trying to follow the examples here: https://github.com/swagger-api/swagger-samples/, but unfortunately this one: https://github.com/swagger-api/swagger-samples/blob/master/java/java-servlet/src/main/java/io/swagge... which is the closest match, uses the 1.x version of swagger.core, not 2.x.

 

I found other examples that sort of work (see what I did below), except that it generates an almost 950 line requestBody element in the openapi.yaml doc for this endpoint. Why does it do that? Is there a way to suppress that? Below is the maven import and the code snippet:

 

<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.1.2</version>

 

The code with annotations is:

 @Path("/Test00020")

 public class Test00020 extends HttpServlet {

 

         @Override

         @GET

         @Operation (

                 summary = "Ask something, get something back.",

                 parameters = { @Parameter(in = ParameterIn.QUERY, name="TestParam00020", required = true ) }

         )

         public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { ...

 

Thanks, Dave

2 ACCEPTED SOLUTIONS

Accepted Solutions
Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

you can hide any parameter including request body via @Parameter.hidden annotation, like:

 

    @Override
    @GET
    @Operation (
        summary = "Ask something, get something back.",
        parameters = { @Parameter(in = ParameterIn.QUERY, name="TestParam00020", required = true ) }
    )
    public void doGet(@Parameter(hidden = true) HttpServletRequest request, @Parameter(hidden = true) HttpServletResponse response) throws ServletException, IOException {
    }

View solution in original post

Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

Did you apply the annotation also to the response? and are you using the latest version?

 

I suspect you didn't hide the response and you're seeing that in your outcome. As mentioned, the reader is targeting JAX-RS methods, therefore it tries to resolve method parameters if not hidden, and response is a method parameter.

 

I tested with the code above and request body is correctly not resolved

View solution in original post

11 REPLIES 11
Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

Hi Dave,

 

"plain" servlets are not supported in 2.x version of swagger-core, as they are in 1.x version.

 

You are probably getting a result anyway because you are using JAX-RS annotations (e.g. `@GET`), which "marks" the servlet method as processable by swagger-core. 

 

In your case I guess swagger-core is processing the request and response as parameters/request body which is clearly not what you want; you can add annotations (swagger-core 2.x ones) to specify parameters, request bodies and responses yourself defining exactly what you need (see swagger-core wiki and swagger-samples branch `2.0`).

 

Highlighted
Occasional Contributor

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

In the case of a normal GET request there is NO requestBody at all. I see how you can create a custom requestBody, per your comment: "you can add annotations (swagger-core 2.x ones) to specify parameters, request bodies and responses yourself defining exactly what you need (see swagger-core wiki and swagger-samples branch `2.0`)". But I see no way to completely suppress it. That's what I'm asking, how do you use swagger-core 2.0 annotations to completely supporess the requestBody. If there isn't any way to do that, maybe create a new feature request?

Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

you can hide any parameter including request body via @Parameter.hidden annotation, like:

 

    @Override
    @GET
    @Operation (
        summary = "Ask something, get something back.",
        parameters = { @Parameter(in = ParameterIn.QUERY, name="TestParam00020", required = true ) }
    )
    public void doGet(@Parameter(hidden = true) HttpServletRequest request, @Parameter(hidden = true) HttpServletResponse response) throws ServletException, IOException {
    }

View solution in original post

Highlighted
Occasional Contributor

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

I'm trying to suppress the entire requireBody, not just the 'request' parameter. Using:

@Parameter(hidden = true) HttpServletRequest request

, doesn't work. As it generates this:

 

      requestBody:

         content:

           '*/*':

             schema:

               type: object

               properties:

                 status:

                   type: integer

                   format: int32

                 headerNames:

                   type: array

                   items:

                     type: string

                 writer:

                   type: object

                 contentType:

LOTS more ... 

 

The closest thing I can come up with is adding this to the @Operation block:

  requestBody = @RequestBody( required = false, content = @Content( ))

 

But it still generates this:

 

      requestBody:

         content:

           '*/*': {}

 

And I need it to omit the requestBody element entirely. What do you suggest at this point?

Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

Did you apply the annotation also to the response? and are you using the latest version?

 

I suspect you didn't hide the response and you're seeing that in your outcome. As mentioned, the reader is targeting JAX-RS methods, therefore it tries to resolve method parameters if not hidden, and response is a method parameter.

 

I tested with the code above and request body is correctly not resolved

View solution in original post

Highlighted
Occasional Contributor

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

OK. That worked. It never occurred to me that I would have to 'hide' the response parameter in order to suppress generation of a requestBody, but after hiding that parameter too, the requestBody was not being generated anymore.

 

Thanks for your help.

Highlighted
Occasional Contributor

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

This solution suppresses requestBody generation, but only if you specify 

@Parameter(hidden = true)

for both the request and response parameters. 

Highlighted
Occasional Contributor

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

A question related to your comment: ""plain" servlets are not supported in 2.x version of swagger-core, as they are in 1.x version."  Is 1.x of swagger-core going to be updated so you can (optionally?) use it on plain servlets to generate a openapi v3.0 compatible spec?  I see that the 1.x branch is still being maintained. Given that it is, seems like having the ability to generate a 3.0 compatible spec in that branch would be desireable. Esp. for someone like me trying to generate openapi docs for old code.

Highlighted
Staff

Re: How to suppress requestBody generation in OpenAPI spec using swagger-maven-plugin

Answer is nope, servlet support can be added to the master 2.x version, to produce OpenAPI 3.0, but 1.x will always be producing only Swagger/OpenAPI 2.0

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors