[Feature]: Need since or reason field in @Hidden annotation

[agongi]

Feature Description

Add reason and since fields to the @hidden annotation in swagger-core.

Currently, the @hidden annotation is a binary toggle that prevents an element from appearing in the OpenAPI definition. However, it provides no context as to why the element was hidden or when that decision was made. Adding these fields would allow developers to document the lifecycle and rationale of API elements directly in the code.

Use Case

Without a reason or since field, team members often have to dive into Git history to understand why something is hidden or added comments in code.

Having this metadata in the code improves maintainability and developer experience.
Similar approach is provided in java @Deprecated(since = "....")

Suggested Solution (optional)

Update the @Hidden annotation to include a reason string (or since like @deprecated)

public @interface Hidden {
    /**
     * The reason why this element is hidden
     */
    String reason() default "";

    /**
     * The version or date since this element was hidden.
     */
    String since() default "";
}

Alternatives Considered

Using // or /** */ comments

Additional Context

Adding such metadata aligns with modern Java practices, similar to how the @deprecated annotation was enhanced to provide more than just a binary state. It improves the self-documenting nature of the source code.

Checklist

• I have searched the existing issues to ensure this is not a duplicate.
• This feature would be useful to more than just my use case.
• I have provided enough detail for the maintainers to understand the scope of the request.

[Mattias-Sehlstedt]

I believe an additional alternative should be to define a local annotation that contains @Hidden but also decorates it with any fields that is found helpful. So something like:

@Target({METHOD, TYPE, FIELD, ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Hidden
public @interface MyHidden {
    /**
     * The reason why this element is hidden
     */
    String reason() default "";

    /**
     * The version or date since this element was hidden.
     */
    String since() default "";
}