adding open-api details to controller endpoints

src/main/java/com/behl/overseer/controller/JokeController.java

@@ -11,6 +11,7 @@
 import com.behl.overseer.utility.JokeGenerator;
 
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.headers.Header;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -29,8 +30,12 @@ public class JokeController {
 	@GetMapping(value = "/joke", produces = MediaType.APPLICATION_JSON_VALUE)
 	@Operation(summary = "Generates a random unfunny joke")
 	@ApiResponses(value = { 
-			@ApiResponse(responseCode = "200", description = "Successfully generated random unfunny joke"),
+			@ApiResponse(responseCode = "200", description = "Successfully generated random unfunny joke",
+					headers = @Header(name = "X-Rate-Limit-Remaining", description = "The number of remaining API invocations available with the user after processing the request.", required = true, 
+							schema = @Schema(type = "integer"))),
 			@ApiResponse(responseCode = "429", description = "API rate limit exhausted",
+					headers = @Header(name = "X-Rate-Limit-Retry-After-Seconds", description = "Wait period in seconds before the user can invoke the API endpoint", required = true, 
+							schema = @Schema(type = "integer")),
 					content = @Content(schema = @Schema(implementation = ExceptionResponseDto.class))) })
 	public ResponseEntity<JokeResponseDto> generate() {
 		final var response = jokeGenerator.generate();

src/main/java/com/behl/overseer/controller/PlanController.java

@@ -45,7 +45,8 @@ public ResponseEntity<List<PlanResponseDto>> retrieve() {
 	@PutMapping(value = "/plan")
 	@Operation(summary = "Update user plan", description = "Updates an existing plan of an authenticated user")
 	@ApiResponses(value = { 
-			@ApiResponse(responseCode = "200", description = "Plan updated successfully"),
+			@ApiResponse(responseCode = "200", description = "Plan updated successfully",
+					content = @Content(schema = @Schema(implementation = Void.class))),
 			@ApiResponse(responseCode = "404", description = "No plan exists in the system with provided-id",
 					content = @Content(schema = @Schema(implementation = ExceptionResponseDto.class))),
 			@ApiResponse(responseCode = "429", description = "API rate limit exhausted",