Openapi Generator. How to generate method with HttpServletResponse as parameter?

Question

everyone.

I use strategy "Design first". I describe specification. One of the methods accepts HttpServletResponse as paramether. But i don't know ho to describe it correctly in my .yaml-fle.

What i tried to write:

/api/method:
    get:
      tags:
        - XXXController
      summary: ~
      description: ~
      operationId: doSomething
      parameters:
        - description: HttpServletResponse
          in: query
          name: response
          required: true
          schema:
            $ref: '#/components/schemas/HttpServletResponse'

In the same time, i added ImportMappings to the build.gradle:

importMappings = [
                     HttpServletResponse: "javax.servlet.http.HttpServletResponse"
    ]

And it doesn't work.

if i place to $ref "real" component, which is described in "components" section - it will be OK.

But it doesn't work with external classes (mapped in importMappings)

I need your help

i expect to get method like this

public void method(HttpServletResponse response);

but i recieve an error:

Errors: 
  -attribute paths.'/method/l'(get).parameters.[response].schemas.#/components/schemas/HttpServletResponse is missing

Answer 1

HttpServletResponse is not something you want to add to the OpenAPI description.

Someone calling your api via http will be very confused about it and won't be able to provide a framework specific java class as parameter.

HttpServletResponse is something you get from your Spring Boot application, e.g. like in your example above. It is an implementation detail.

Since HttpServletResponse it is not part of the API and you don't have direct control over the signature of the generated api method the generator must provide code to access the HttpServletResponse.

I'm not an openapi-generator expert, but using a small test project it generates code like this:

@Controller
@RequestMapping("${openapi.sample.base-path:}")
public class FooApiController implements FooApi {

    private final NativeWebRequest request;

    @org.springframework.beans.factory.annotation.Autowired
    public FooApiController(NativeWebRequest request) {
        this.request = request;
    }

    @Override
    public Optional<NativeWebRequest> getRequest() {
        return Optional.ofNullable(request);
    }
}

You can then use NativeRequest from your endpoint implementation to get the response object.

...

openapi-processor (I'm the author) is an alternative generator that's using a different way to provide access to HttpServletResponse.

Having an api:

openapi: 3.0.2
info:
  title: test additional endpoint parameters
  version: 1.0.0

paths:
  /foo:
    get:
      parameters:
        - name: foo
          description: query, required
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: empty

and a few extra lines of configuration:

# snippet from the yaml configuration

  paths:
    /foo:
      parameters:
        - add: response => javax.servlet.http.HttpServletResponse

it will generate a (interface) method with an additional HttpServletResponse parameter:

@GetMapping(path = "/foo")
void getFoo(@RequestParam(name = "foo") String foo, HttpServletResponse response);