@Getter @Setter  // adds getters and setters to all fields
public class ResponseEnvelope<T> {
    private int status;
    private ResponseVersion version;
    private T data;
    private String error;
}

{
  "status": 200,
  "version": {
    "major": "1",
    "minor": "23"
  },
  "data": {
    "user": {
      "firstName": "Fred",
      "lastName": "Flintstone"
    }
  },
  "error": null
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiController {

    /**
     * Base path for mappings.
     */
    String base();

    /**
     * Title of the controller for OpenApi docs.
     */
    String title() default "";

    /**
     * Description of the controller for OpenApi docs.
     */
    String desc() default "";
}

/**
 * All endpoint URLs in this class are prefixed with "/mycontroller".
 */
@ApiController(
        base = "/mycontroller",
        title = "These endpoints related to foo",
        desc = "This is a more detailed description.")
public class MyController {
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiEndpoint {

    /**
     * Sets the URL path of the associated GET operation.
     */
    String GET() default "";

    /**
     * Sets the URL path of the associated PUT operation.
     */
    String PUT() default "";

    /**
     * Sets the URL path of the associated POST operation.
     */
    String POST() default "";

    /**
     * Sets the URL path of the associated DELETE operation.
     */
    String DELETE() default "";

    /**
     * Description of the endpoint.
     */
    String desc();

    /**
     * Documents the URL parameters. Name of @Param should match a named parameter
     * in the request handler.
     */
    Param[] params() default {};

    @Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface Param {

        /**
         * Name of a parameter in the request handler. Name must match
         * for the documentation to be displayed.
         */
        String name();

        /**
         * Description of the parameter.
         */
        String desc();
    }

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "GET {base}/mycontroller/fetch" is hit,
     * then this method is called.
     */
    @ApiEndpoint(GET = "/fetch", desc = "This is what this endpoint does")
    public SomeBeanType fetch() {
        // fetch SomeBeanType here and return it
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "POST {base}/mycontroller/method1" is called,
     * this method returns version "1.0" in the payload envelope.
     */
    @ApiEndpoint(POST = "/method1", desc = "")
    public void method1() {
    }

    /**
     * When "POST {base}/mycontroller/method2" is called,
     * this method returns version "4.56" in the payload envelope.
     */
    @ApiVersion("4.56")
    @ApiEndpoint(PUT = "/method2", desc = "")
    public void method2() {
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "GET {base}/mycontroller/br-549" is called,
     * the object whose handle is "br-549" is passed in the "bean" variable.
     */
    @ApiEndpoint(GET = "/something/{handle}", desc = "")
    public void getBean(@HandleVariable("handle") SomeBean someBean) {
        // use the someBean object
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "GET {base}/mycontroller/user/63" is called,
     * the method parameter "id" has a value of 63.
     */
    @ApiEndpoint(GET = "/user/{id}", desc = """
        This is a multi-line description that can go on and on and on.
        It can be in Markdown format and can contain blank lines.""",
        params = @Param(name = "id", desc = "The unique 6-digit integer"))
    public SomeBeanType getBean(@PathVariable("id") Integer id) {
        // return
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "POST {base}/mycontroller/user/save" is called,
     * the method parameter "userBean" is populated from the request's body.
     */
    @ApiEndpoint(POST = "/user/save", desc = "")
    public void saveUser(@RequestBody UserBean userBean) {
        // process userBean object
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "GET {base}/mycontroller/user/list?order=firstName&limit=10" is called,
     * the method parameter "order" contains "firstName", and
     * the method parameter "limit" is 10.
     * As you can see, "order" is required, but "limit" is not.
     */
    @ApiEndpoint(GET = "/user/list", desc = "")
    public List<UserBean> listUsers(
            @RequestParam(value = "order", required = true) String order,
            @RequestParam(value = "limit", defaultValue = 20) Integer limit) {
        // process request
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    /**
     * When "GET {base}/mycontroller/file/data.json" is called,
     * the method parameter "fileName" contains "data.json".
     * The resulting stream of bytes is returned to the httpResponse.getOutputStream().
     */
    @ApiEndpoint(GET = "/file/{name}", desc = "")
    @ResponseStream
    public void serveContent(HttpResponse httpResponse, @PathVariable("name") String fileName) {
        // send bytes to the httpResponse's output stream
    }
}

@ApiController(base = "/mycontroller")
public class MyController {

    @ApiEndpoint(POST = "/pump/{pump}/start", desc = "")
    public void startPump(@HandleVariable("pump") Pump pump, @Tracker String tracker) {
        pumpService.start(pump, tracker);
    }
}

public interface HttpRequest extends AttributeAware {

    String getPath();
    RequestMethod getMethod();

    InputStream getInputStream() throws IOException;
    JsonNode getJsonBody();

    String getParameter(String name);
    MultiValueMap<String, String> getParameters();

    InetSocketAddress getClientAddress();

    String getHeader(String name);
    Collection<String> getHeaders(String name);
    Collection<String> getHeaderNames();
}

@ApiController(base = "/mycontroller")
public class MyController {

    @ApiEndpoint(GET = "/whatever", desc = "")
    public void startPump(HttpRequest httpRequest) {
        // use the httpRequest variable
    }
}

public interface HttpResponse {

    OutputStream getOutputStream() throws IOException;

    void setHeader(String name, String val);
    void setDateHeader(String name, long date);

    int getStatus();
    void setStatus(int status);

    void sendError(int status) throws IOException;
}

@ApiController(base = "/mycontroller")
public class MyController {

    @ApiEndpoint(GET = "/whatever", desc = "")
    public void startPump(HttpResponse httpResponse) {
        // use the httpResponse variable
    }
}