Core API Documentation

/**
 * Marks a class as a Swagger resource
 * Target: TYPE (classes)
 * Retention: RUNTIME
 * Inherited: true
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@interface Api {
    /** 
     * Implicitly sets a tag for operations (legacy support)
     * If tags() is not used, this value sets the tag for operations
     * Leading / is removed if present
     */
    String value() default "";
    
    /**
     * Array of tags for API documentation control
     * Used for logical grouping of operations by resources
     * Overrides value() if non-empty
     */
    String[] tags() default "";
    
    /** @deprecated Not used in 1.5.X, kept for legacy support */
    String description() default "";
    
    /** @deprecated Not used in 1.5.X, kept for legacy support */
    String basePath() default "";
    
    /** @deprecated Not used in 1.5.X, kept for legacy support */
    int position() default 0;
    
    /**
     * Corresponds to 'produces' field of operations under this resource
     * Comma-separated content types (e.g., "application/json, application/xml")
     * Automatically takes JAX-RS @Produces value if present, can override
     */
    String produces() default "";
    
    /**
     * Corresponds to 'consumes' field of operations under this resource  
     * Comma-separated content types for accepted input
     * Automatically takes JAX-RS @Consumes value if present, can override
     */
    String consumes() default "";
    
    /**
     * Sets specific protocols (schemes) for operations under this resource
     * Comma-separated values: http, https, ws, wss
     */
    String protocols() default "";
    
    /**
     * Corresponds to 'security' field of Operation Object
     * List of authorizations (security requirements) for operations
     * May be overridden by specific operations
     */
    Authorization[] authorizations() default @Authorization(value = "");
    
    /** Hides the operations under this resource */
    boolean hidden() default false;
}

// Basic API marking
@Api
@Path("/users")
public class UserController {
    // operations
}

// API with tags and content types
@Api(
    tags = {"users", "management"}, 
    produces = "application/json",
    consumes = "application/json"
)
@Path("/users")
public class UserController {
    // operations
}

// API with security requirements
@Api(
    tags = "admin",
    authorizations = {
        @Authorization(value = "oauth2", scopes = {
            @AuthorizationScope(scope = "admin", description = "Admin access")
        })
    }
)
@Path("/admin")
public class AdminController {
    // operations
}

/**
 * Describes an operation or HTTP method against a specific path
 * Target: METHOD, TYPE
 * Retention: RUNTIME
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface ApiOperation {
    /**
     * Corresponds to 'summary' field of the operation
     * Brief description of operation (should be ≤120 characters for Swagger-UI)
     * REQUIRED ATTRIBUTE
     */
    String value();
    
    /**
     * Corresponds to 'notes' field of the operation
     * Verbose description of the operation
     */
    String notes() default "";
    
    /**
     * List of tags for API documentation control
     * Used for logical grouping of operations by resources
     * Overrides value from @Api#value() or @Api#tags() for this operation
     */
    String[] tags() default "";
    
    /**
     * Response type of the operation
     * In JAX-RS, return type is used automatically unless it's Response
     * Setting this property overrides automatically-derived data type
     * Primitive class wrappers (Integer, Long) use corresponding primitives
     */
    Class<?> response() default Void.class;
    
    /**
     * Declares a container wrapping the response
     * Valid values: "List", "Set", "Map" (other values ignored)
     */
    String responseContainer() default "";
    
    /**
     * Specifies reference to response type
     * Can be local or remote, used as-is
     * Overrides any specified response() class
     */
    String responseReference() default "";
    
    /**
     * Corresponds to 'method' field as HTTP method used
     * For JAX-RS: @GET, @HEAD, @POST, @PUT, @DELETE, @OPTIONS scanned automatically
     * @PATCH also supported though not in JAX-RS spec
     * For Servlets: must specify HTTP method manually
     * Acceptable values: "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"
     */
    String httpMethod() default "";
    
    /** @deprecated Not used in 1.5.X, kept for legacy support */
    int position() default 0;
    
    /**
     * Corresponds to 'operationId' field
     * Used by third-party tools to uniquely identify operation
     * No longer mandatory in Swagger 2.0
     */
    String nickname() default "";
    
    /**
     * Corresponds to 'produces' field of the operation
     * Comma-separated content types this operation generates
     * Automatically takes JAX-RS @Produces value, can override
     */
    String produces() default "";
    
    /**
     * Corresponds to 'consumes' field of the operation
     * Comma-separated content types this operation accepts
     * Automatically takes JAX-RS @Consumes value, can override  
     */
    String consumes() default "";
    
    /**
     * Sets specific protocols (schemes) for this operation
     * Comma-separated values: http, https, ws, wss
     */
    String protocols() default "";
    
    /**
     * Corresponds to 'security' field of Operation Object
     * List of authorizations (security requirements) for this operation
     */
    Authorization[] authorizations() default @Authorization(value = "");
    
    /** Hides the operation from the list of operations */
    boolean hidden() default false;
    
    /**
     * List of possible headers provided alongside the response
     */
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
    
    /**
     * HTTP status code of the response
     * Should be formal HTTP Status Code (see RFC 2616)
     */
    int code() default 200;
    
    /** Optional array of extensions */
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
    
    /** Ignores JsonView annotations while resolving operations and types */
    boolean ignoreJsonView() default false;
}

// Basic operation
@ApiOperation(value = "Get user by ID")
@GET
@Path("/{id}")
public User getUser(@PathParam("id") Long id) {
    // implementation
}

// Detailed operation with response info
@ApiOperation(
    value = "Create new user",
    notes = "Creates a new user account with the provided information. Returns the created user with assigned ID.",
    response = User.class,
    code = 201,
    tags = {"users", "creation"}
)
@POST
public Response createUser(User user) {
    // implementation
}

// Operation with custom response headers
@ApiOperation(
    value = "Upload user avatar",
    responseHeaders = {
        @ResponseHeader(name = "Location", description = "URL of uploaded image", response = String.class),
        @ResponseHeader(name = "Content-Length", description = "Size of uploaded file", response = Long.class)
    }
)
@POST
@Path("/{id}/avatar")
public Response uploadAvatar(@PathParam("id") Long id, InputStream imageData) {
    // implementation
}

// Operation with security requirements
@ApiOperation(
    value = "Delete user account",
    notes = "Permanently deletes a user account. This action cannot be undone.",
    authorizations = {
        @Authorization(value = "oauth2", scopes = {
            @AuthorizationScope(scope = "user:delete", description = "Delete user accounts")
        })
    }
)
@DELETE
@Path("/{id}")
public Response deleteUser(@PathParam("id") Long id) {
    // implementation
}

// Operation with collection response
@ApiOperation(
    value = "List all users",
    response = User.class,
    responseContainer = "List"
)
@GET
public List<User> getAllUsers() {
    // implementation
}

@Api(tags = "products", produces = "application/json")
@Path("/products")
@Produces(MediaType.APPLICATION_JSON) // Swagger automatically detects this
@Consumes(MediaType.APPLICATION_JSON)
public class ProductController {

    @ApiOperation(value = "Search products")
    @GET // Swagger automatically detects HTTP method
    public List<Product> searchProducts(
        @QueryParam("q") String query,
        @QueryParam("category") String category
    ) {
        // JAX-RS annotations work alongside Swagger annotations
    }
    
    @ApiOperation(
        value = "Get product details", 
        response = Product.class
    )
    @GET
    @Path("/{id}")
    public Product getProduct(@PathParam("id") Long id) {
        // Path parameters automatically detected
    }
}