Description
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