tessl/maven-io-swagger--swagger-annotations

Java annotations for defining Swagger API documentation and OpenAPI specification metadata

—

Pending

Overview

Eval results

Files

Parameter Documentation

Name: tessl/maven-io-swagger--swagger-annotations
Author: tessl

Annotations for documenting API parameters, including path parameters, query parameters, form parameters, and request bodies. These annotations provide detailed metadata about parameter types, constraints, and validation rules.

Capabilities

@ApiParam Annotation

Adds additional metadata for operation parameters. This annotation can only be used in combination with JAX-RS annotations.

/**
 * Adds additional meta-data for operation parameters
 * Can only be used with JAX-RS annotations
 * Target: PARAMETER, METHOD, FIELD
 * Retention: RUNTIME
 */
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@interface ApiParam {
    /**
     * The parameter name
     * Derived from field/method/parameter name if not specified
     * Path parameters must always match the path section they represent
     */
    String name() default "";
    
    /** Brief description of the parameter */
    String value() default "";
    
    /**
     * Describes the default value for the parameter
     * JAX-RS @DefaultValue is used if available, can be overridden
     */
    String defaultValue() default "";
    
    /**
     * Limits acceptable values for this parameter
     * Three formats supported:
     * 1. List: "first, second, third"
     * 2. Range: "range[1, 5]", "range(1, 5)", "range[1, 5)"
     * 3. Min/Max: "range[1, infinity]", "range[-infinity, 100]"
     */
    String allowableValues() default "";
    
    /**
     * Specifies if parameter is required
     * Path parameters are always required regardless of this setting
     */
    boolean required() default false;
    
    /**
     * Allows filtering parameter from API documentation
     * See io.swagger.core.filter.SwaggerSpecFilter for details
     */
    String access() default "";
    
    /** Specifies whether parameter can accept multiple values */
    boolean allowMultiple() default false;
    
    /** Hides parameter from the list of parameters */
    boolean hidden() default false;
    
    /** Single example for non-body type parameters */
    String example() default "";
    
    /** Examples for the parameter (applies only to BodyParameters) */
    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
    
    /** Adds ability to override the detected type */
    String type() default "";
    
    /** Adds ability to provide a custom format */
    String format() default "";
    
    /** Adds ability to set a format as empty */
    boolean allowEmptyValue() default false;
    
    /** Adds ability to be designated as read only */
    boolean readOnly() default false;
    
    /** Adds ability to override collectionFormat with array types */
    String collectionFormat() default "";
}

Usage Examples:

// Basic parameter documentation
@GET
@Path("/users/{id}")
public User getUser(
    @ApiParam(value = "User ID", required = true)
    @PathParam("id") Long id
) {
    // implementation
}

// Query parameter with constraints
@GET
@Path("/users")
public List<User> searchUsers(
    @ApiParam(
        value = "Search query", 
        example = "john doe"
    )
    @QueryParam("q") String query,
    
    @ApiParam(
        value = "Results per page",
        defaultValue = "10",
        allowableValues = "range[1, 100]"
    )
    @QueryParam("limit") @DefaultValue("10") Integer limit,
    
    @ApiParam(
        value = "User status filter",
        allowableValues = "active, inactive, pending"
    )
    @QueryParam("status") String status
) {
    // implementation
}

// Form parameter with examples
@POST
@Path("/users")
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response createUser(
    @ApiParam(value = "User name", required = true, example = "John Doe")
    @FormParam("name") String name,
    
    @ApiParam(value = "Email address", required = true, example = "john@example.com")
    @FormParam("email") String email,
    
    @ApiParam(value = "User age", allowableValues = "range[18, 120]")
    @FormParam("age") Integer age
) {
    // implementation
}

// Body parameter with complex example
@PUT
@Path("/users/{id}")
public Response updateUser(
    @ApiParam(value = "User ID", required = true)
    @PathParam("id") Long id,
    
    @ApiParam(
        value = "Updated user data",
        required = true,
        examples = @Example(value = {
            @ExampleProperty(
                mediaType = "application/json",
                value = "{\"name\": \"John Smith\", \"email\": \"john.smith@example.com\"}"
            )
        })
    )
    User user
) {
    // implementation
}

@ApiImplicitParam Annotation

Alternative parameter documentation for non-JAX-RS environments (like Servlets) or when you need to document parameters that aren't explicitly declared in method signatures.

/**
 * Implicitly documents a parameter when it's not explicitly in method signature
 * Useful for Servlet environments or framework-managed parameters
 * Target: METHOD, TYPE
 * Retention: RUNTIME
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface ApiImplicitParam {
    /** Parameter name */
    String name() default "";
    
    /** Brief description of the parameter */
    String value() default "";
    
    /** Default value for the parameter */
    String defaultValue() default "";
    
    /** Allowable values for the parameter (same format as @ApiParam) */
    String allowableValues() default "";
    
    /** Whether the parameter is required */
    boolean required() default false;
    
    /** 
     * Data type of the parameter
     * Java class name or primitive type
     */
    String dataType() default "";
    
    /** Data type as a class reference */
    String dataTypeClass() default "";
    
    /**
     * Parameter type specifying where parameter is located
     * Valid values: "query", "header", "path", "formData", "body"
     */
    String paramType() default "";
    
    /** Access level for filtering */
    String access() default "";
    
    /** Whether parameter accepts multiple values */
    boolean allowMultiple() default false;
    
    /** Parameter format (e.g., "date", "date-time", "binary") */
    String format() default "";
    
    /** Whether parameter allows empty values */
    boolean allowEmptyValue() default false;
    
    /** Whether parameter is read-only */
    boolean readOnly() default false;
    
    /** Collection format for array parameters */
    String collectionFormat() default "";
    
    /** Example value for the parameter */
    String example() default "";
}

Usage Examples:

// Servlet-style parameter documentation
@ApiImplicitParam(
    name = "userId",
    value = "ID of the user to retrieve",
    required = true,
    dataType = "long",
    paramType = "path"
)
@GET
@Path("/users/{userId}")
public Response getUserServlet(HttpServletRequest request) {
    Long userId = Long.parseLong(request.getPathInfo().split("/")[2]);
    // implementation
}

// Header parameter documentation
@ApiImplicitParam(
    name = "X-API-Version",
    value = "API version to use",
    dataType = "string",
    paramType = "header",
    defaultValue = "v1",
    allowableValues = "v1, v2"
)
@GET
@Path("/users")
public List<User> getUsers(HttpServletRequest request) {
    String version = request.getHeader("X-API-Version");
    // implementation
}

// Body parameter for complex types
@ApiImplicitParam(
    name = "user",
    value = "User data to create",
    required = true,
    dataType = "User",
    paramType = "body"
)
@POST
@Path("/users")
public Response createUserServlet(HttpServletRequest request) {
    // Parse JSON from request body
    // implementation
}

@ApiImplicitParams Annotation

Container annotation for multiple implicit parameters.

/**
 * Container for multiple @ApiImplicitParam annotations
 * Target: METHOD, ANNOTATION_TYPE, TYPE
 * Retention: RUNTIME
 */
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface ApiImplicitParams {
    /** Array of implicit parameter definitions */
    ApiImplicitParam[] value();
}

Usage Examples:

// Multiple implicit parameters
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "Authorization",
        value = "JWT token for authentication",
        required = true,
        dataType = "string",
        paramType = "header"
    ),
    @ApiImplicitParam(
        name = "page",
        value = "Page number for pagination",
        dataType = "int",
        paramType = "query",
        defaultValue = "1"
    ),
    @ApiImplicitParam(
        name = "size",
        value = "Number of items per page",
        dataType = "int", 
        paramType = "query",
        defaultValue = "20",
        allowableValues = "range[1, 100]"
    )
})
@GET
@Path("/users")
public Response getUsers(HttpServletRequest request) {
    // implementation using servlet API
}

// Mixed parameter types
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "file",
        value = "File to upload",
        required = true,
        dataType = "__file",
        paramType = "formData"
    ),
    @ApiImplicitParam(
        name = "description", 
        value = "File description",
        dataType = "string",
        paramType = "formData"
    ),
    @ApiImplicitParam(
        name = "Content-Type",
        value = "MIME type of the file",
        dataType = "string",
        paramType = "header",
        defaultValue = "application/octet-stream"
    )
})
@POST
@Path("/upload")
public Response uploadFile(HttpServletRequest request) {
    // Handle file upload
}

Parameter Type Reference

Common parameter types and their usage:

// Path parameters - always required
@ApiParam(value = "Resource ID", required = true)
@PathParam("id") Long id

// Query parameters - optional by default  
@ApiParam(value = "Filter criteria")
@QueryParam("filter") String filter

// Header parameters
@ApiParam(value = "API version")
@HeaderParam("X-API-Version") String version

// Form parameters
@ApiParam(value = "Form field")
@FormParam("field") String field

// Body parameters (entire request body)
@ApiParam(value = "Request payload", required = true)
RequestDto request

Validation and Constraints

// Numeric ranges
@ApiParam(
    value = "Age in years",
    allowableValues = "range[0, 150]"
)
@QueryParam("age") Integer age

// Enumerated values
@ApiParam(
    value = "Sort order",
    allowableValues = "asc, desc"
)
@QueryParam("sort") String sort

// Multiple values
@ApiParam(
    value = "Category IDs",
    allowMultiple = true
)
@QueryParam("categories") List<Long> categories

// File upload
@ApiParam(
    value = "File to upload",
    type = "file"
)
@FormDataParam("file") InputStream fileInputStream

Best Practices

Use @ApiParam with JAX-RS - Preferred for JAX-RS applications
Use @ApiImplicitParam for Servlets - When parameters aren't in method signature
Always document required parameters - Set required = true for mandatory parameters
Provide examples - Help developers understand expected parameter format
Use allowableValues - Document valid parameter values and ranges
Match parameter names - Ensure names match actual parameter names
Document constraints - Include validation rules and limits
Use appropriate paramType - Specify correct parameter location (query, header, path, etc.)

Install with Tessl CLI

npx tessl i tessl/maven-io-swagger--swagger-annotations

docs

tessl/maven-io-swagger--swagger-annotations

parameters.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Parameter Documentation

Capabilities

@ApiParam Annotation

@ApiImplicitParam Annotation

@ApiImplicitParams Annotation

Parameter Type Reference

Validation and Constraints

Best Practices

parameters.mddocs/