Create an annotation the add at controller level to summarize information regarding failed http responses.

Story Title
As a developer, I want to use a @FailedHttpResponse annotation so that I can quickly document common failed HTTP responses at the controller level.

Description
Currently, developers need to repeatedly declare common error responses (401, 403, 404, 500) for each API endpoint using multiple @ApiResponse annotations. This creates boilerplate code and makes API documentation harder to maintain.

The new @FailedHttpResponse meta-annotation will bundle these common error responses into a single reusable annotation that can be applied at both method and class levels.

Acceptance Criteria

• Annotation is added to the io.swagger.v3.oas.annotations package
• Annotation includes the following default responses:
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 500 Internal Server Error
• Annotation can be used at both class and method levels
• Annotation is properly documented with JavaDoc
• Unit tests demonstrate the annotation's functionality
• Documentation is updated to include the new annotation

Technical Details
Package: io.swagger.v3.oas.annotations
Annotation Name: @FailedHttpResponse
Meta-annotations:

@Target({ElementType.METHOD, ElementType.TYPE})

@Retention(RetentionPolicy.RUNTIME)

Composed of multiple @ApiResponse annotations

Implementation Tasks

• Create new annotation file in correct package
• Implement annotation with all required meta-annotations
• Write comprehensive JavaDoc documentation
• Update Swagger documentation to mention the new annotation
• Create example usage in documentation

Example Usage
java

@RestController
@FailedHttpResponse
public class UserController {
    
    @GetMapping("/users/{id}")
    @FailedHttpResponse // Optional method-level override
    public User getUser(@PathVariable String id) {
        // implementation
    }
}

Dependencies
Requires Swagger Core v3.x

No breaking changes to existing functionality

Out of Scope
Customizing the default responses (will be handled in a future enhancement)

Adding additional response codes to the default set

Definition of Done

• Code is submitted via GitHub PR
• PR passes all CI checks
• Code is reviewed and approved by at least one maintainer
• Documentation is updated
• Changes are merged to main branch

Start in the io.swagger.v3.oas.annotations package and compare the requested annotation with existing @ApiResponse usage; verify the four default responses and METHOD/TYPE behavior. Then check the unit-test and Swagger documentation requirements, with done defined by passing tests and updated documentation.