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

Open Source Swagger OS
, , ,
1

Originally posted by wichers on June 17, 2020

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/swagger/sample/servlet/SampleServlet.java 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:

io.swagger.core.v3
swagger-maven-plugin
2.1.2

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

Originally posted by frantuma on June 24, 2020

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

3

Originally posted by wichers on June 24, 2020

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?

4

Originally posted by frantuma on June 25, 2020

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 {
    }
5

Originally posted by wichers on June 25, 2020

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?

6

Originally posted by frantuma on June 27, 2020

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

7

Originally posted by wichers on June 29, 2020

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.

8

Originally posted by wichers on June 29, 2020

This solution suppresses requestBody generation, but only if you specify

@Parameter(hidden = true)

for both the request and response parameters.

9

Originally posted by wichers on June 30, 2020

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.

10

Originally posted by frantuma on July 01, 2020

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

11

Originally posted by wichers on July 01, 2020

OK. Any plans to add Servlet support to the 2.x version as that capability apparently got dropped from 1.x to 2.x? Given it was already implemented before, I’m hoping it wouldn’t be that hard. But I could be very wrong on that.

12

Originally posted by frantuma on July 04, 2020

no short term plans atm, but any contribution is as usual more than welcome