CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Java annotations for defining Swagger API documentation and OpenAPI specification metadata

—

Pending
Overview
Eval results
Files

documentation.mddocs/

Documentation Metadata

Annotations for providing high-level API documentation metadata, external references, and configuration. These annotations define the overall structure and description of the API specification, including contact information, licensing, and external documentation links.

Capabilities

@Tag Annotation

Defines API tags for logical grouping of operations. Tags are used to organize operations in the Swagger-UI and provide metadata about groups of related endpoints.

/**
 * Defines API tags for operation grouping
 * Target: ANNOTATION_TYPE
 * Retention: RUNTIME
 */
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Tag {
    /**
     * Name of the tag
     * Used as the identifier for grouping operations
     * REQUIRED ATTRIBUTE
     */
    String name();
    
    /**
     * Short description for the tag
     * Displayed in Swagger-UI alongside the tag name
     */
    String description() default "";
    
    /**
     * Additional external documentation for this tag
     */
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
    
    /** Optional array of extensions */
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
}

Usage Examples:

// Basic tag definition
@SwaggerDefinition(
    tags = {
        @Tag(name = "users"),
        @Tag(name = "products")
    }
)
public class ApiConfiguration {
}

// Tag with description and external docs
@SwaggerDefinition(
    tags = {
        @Tag(
            name = "authentication", 
            description = "Operations related to user authentication and authorization",
            externalDocs = @ExternalDocs(
                value = "Authentication Guide",
                url = "https://docs.example.com/auth"
            )
        )
    }
)
public class ApiConfiguration {
}

// Multiple detailed tags
@SwaggerDefinition(
    tags = {
        @Tag(
            name = "users",
            description = "User management operations",
            externalDocs = @ExternalDocs(
                value = "User Management Documentation",
                url = "https://docs.example.com/users"
            )
        ),
        @Tag(
            name = "orders",
            description = "Order processing and management",
            externalDocs = @ExternalDocs(
                value = "Order Processing Guide",
                url = "https://docs.example.com/orders"
            )
        )
    }
)
public class ECommerceApiConfiguration {
}

@ExternalDocs Annotation

References external documentation for operations, parameters, or the API itself. Provides a way to link to additional documentation outside of the Swagger specification.

/**
 * References external documentation
 * Target: PARAMETER, METHOD, FIELD
 * Retention: RUNTIME
 */
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@interface ExternalDocs {
    /**
     * Description of the external documentation
     * Brief explanation of what the external resource contains
     */
    String value() default "";
    
    /**
     * URL of the external documentation
     * Must be a valid URL pointing to the documentation resource
     * REQUIRED ATTRIBUTE
     */
    String url();
}

Usage Examples:

// External docs on API operation
@ApiOperation(
    value = "Complex calculation endpoint",
    notes = "Performs advanced mathematical calculations"
)
@ExternalDocs(
    value = "Mathematical Formula Reference",
    url = "https://docs.example.com/math-formulas"
)
@POST
@Path("/calculate")
public CalculationResult performCalculation(CalculationInput input) {
    // implementation
}

// External docs on model field
public class PaymentRequest {
    @ApiModelProperty(value = "Credit card number")
    @ExternalDocs(
        value = "PCI Compliance Guidelines",
        url = "https://www.pcisecuritystandards.org/"
    )
    private String cardNumber;
    
    @ApiModelProperty(value = "CVV security code")
    @ExternalDocs(
        value = "CVV Security Information",
        url = "https://docs.example.com/security/cvv"
    )
    private String cvv;
}

// External docs on parameter
@ApiOperation(value = "Search products")
@GET
@Path("/search")
public List<Product> searchProducts(
    @ApiParam(value = "Search query string")
    @ExternalDocs(
        value = "Search Syntax Documentation", 
        url = "https://docs.example.com/search-syntax"
    )
    @QueryParam("q") String query
) {
    // implementation
}

@SwaggerDefinition Annotation

Configures definition-level metadata for the entire Swagger specification. This annotation is used to define global settings that apply to the entire API, including host, base path, security definitions, and API metadata.

/**
 * Configures definition-level metadata for Swagger specification
 * Target: TYPE
 * Retention: RUNTIME
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface SwaggerDefinition {
    /**
     * Host (name or IP) serving the API
     * Excludes scheme, port, and path
     * May include port number (e.g., "example.com:8080")
     */
    String host() default "";
    
    /**
     * Base path on which the API is served
     * Relative to the host, must start with "/"
     */
    String basePath() default "";
    
    /**
     * List of MIME types the APIs can consume
     * Global default for all operations
     * Can be overridden by individual operations
     */
    String[] consumes() default "";
    
    /**
     * List of MIME types the APIs can produce  
     * Global default for all operations
     * Can be overridden by individual operations
     */
    String[] produces() default "";
    
    /**
     * Transfer protocol for the API
     * Options: HTTP, HTTPS, WS, WSS, or DEFAULT
     */
    Scheme[] schemes() default Scheme.DEFAULT;
    
    /**
     * List of tags used by the specification
     * Provides metadata about the groups of operations
     */
    Tag[] tags() default @Tag(name = "");
    
    /**
     * Security scheme definitions available for use
     */
    SecurityDefinition securityDefinition() default @SecurityDefinition();
    
    /**
     * General information about the API
     * Includes title, version, description, contact, and license
     */
    Info info() default @Info(title = "", version = "");
    
    /**
     * Additional external documentation for this API
     */
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
}

Usage Examples:

// Basic API configuration
@SwaggerDefinition(
    info = @Info(
        title = "E-Commerce API",
        version = "1.0.0"
    ),
    host = "api.example.com",
    basePath = "/v1"
)
public class ApiConfiguration {
}

// Comprehensive API configuration
@SwaggerDefinition(
    info = @Info(
        title = "E-Commerce Platform API",
        version = "2.1.0",
        description = "RESTful API for managing products, orders, and customers",
        contact = @Contact(
            name = "API Support Team",
            email = "api-support@example.com",
            url = "https://support.example.com"
        ),
        license = @License(
            name = "MIT License",
            url = "https://opensource.org/licenses/MIT"
        )
    ),
    host = "api.example.com",
    basePath = "/v2",
    schemes = {Scheme.HTTPS},
    consumes = {"application/json", "application/xml"},
    produces = {"application/json", "application/xml"},
    tags = {
        @Tag(name = "products", description = "Product catalog management"),
        @Tag(name = "orders", description = "Order processing"),
        @Tag(name = "customers", description = "Customer management"),
        @Tag(name = "authentication", description = "Authentication and authorization")
    },
    securityDefinition = @SecurityDefinition(
        apiKeyAuthDefinitions = {
            @ApiKeyAuthDefinition(
                key = "api_key",
                name = "X-API-Key",
                in = ApiKeyLocation.HEADER,
                description = "API key for authentication"
            )
        },
        oAuth2Definitions = {
            @OAuth2Definition(
                key = "oauth2",
                flow = Flow.ACCESS_CODE,
                authorizationUrl = "https://auth.example.com/oauth/authorize",
                tokenUrl = "https://auth.example.com/oauth/token",
                scopes = {
                    @Scope(name = "read", description = "Read access to resources"),
                    @Scope(name = "write", description = "Write access to resources"),
                    @Scope(name = "admin", description = "Administrative access")
                }
            )
        }
    ),
    externalDocs = @ExternalDocs(
        value = "Full API Documentation",
        url = "https://docs.example.com/api"
    )
)
public class ECommerceApiConfiguration {
}

// Development vs Production configuration
@SwaggerDefinition(
    info = @Info(
        title = "Development API",
        version = "1.0.0-SNAPSHOT",
        description = "Development version of the API - not for production use"
    ),
    host = "localhost:8080",
    basePath = "/api",
    schemes = {Scheme.HTTP}
)
public class DevApiConfiguration {
}

@Info Annotation

Provides high-level metadata about the API including title, version, description, and contact information. This annotation is used within @SwaggerDefinition to define the API's basic information.

/**
 * Provides high-level API metadata
 * Target: ANNOTATION_TYPE
 * Retention: RUNTIME
 */
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Info {
    /**
     * Title of the application
     * Used as the main heading in Swagger-UI
     * REQUIRED ATTRIBUTE
     */
    String title();
    
    /**
     * Version of the OpenAPI document
     * Distinct from API implementation version
     * REQUIRED ATTRIBUTE
     */
    String version();
    
    /**
     * Short description of the application
     * CommonMark syntax can be used for rich text representation
     */
    String description() default "";
    
    /**
     * URL to the Terms of Service for the API
     * Must be in URL format
     */
    String termsOfService() default "";
    
    /**
     * Contact information for the exposed API
     */
    Contact contact() default @Contact(name = "");
    
    /**
     * License information for the exposed API
     */
    License license() default @License(name = "");
    
    /** Optional array of extensions */
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
}

Usage Examples:

// Basic info
@SwaggerDefinition(
    info = @Info(
        title = "Product Catalog API",
        version = "1.0.0"
    )
)

// Detailed info with contact and license
@SwaggerDefinition(
    info = @Info(
        title = "E-Commerce Platform API",
        version = "2.1.0",
        description = "Comprehensive API for managing an e-commerce platform including products, orders, customers, and payments. " +
                     "This API follows RESTful principles and provides both JSON and XML response formats.",
        termsOfService = "https://example.com/terms",
        contact = @Contact(
            name = "Platform Engineering Team",
            email = "platform-eng@example.com", 
            url = "https://example.com/support"
        ),
        license = @License(
            name = "Apache License 2.0",
            url = "https://www.apache.org/licenses/LICENSE-2.0"
        )
    )
)

// Beta version with warnings
@SwaggerDefinition(
    info = @Info(
        title = "Analytics API (Beta)",
        version = "0.9.0-beta",
        description = "**BETA VERSION**: Advanced analytics and reporting API. " +
                     "This API is in beta and may undergo breaking changes. " +
                     "Use with caution in production environments.",
        contact = @Contact(
            name = "Analytics Team",
            email = "analytics@example.com"
        )
    )
)

@Contact Annotation

Defines contact information for the API including name, URL, and email. Used within @Info to provide contact details for API consumers.

/**
 * Defines contact information for API
 * Target: ANNOTATION_TYPE
 * Retention: RUNTIME
 */
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface Contact {
    /**
     * Identifying name of the contact person/organization
     * REQUIRED ATTRIBUTE
     */
    String name();
    
    /**
     * URL pointing to the contact information
     * Must be in URL format
     */
    String url() default "";
    
    /**
     * Email address of the contact person/organization
     * Must be in email format
     */
    String email() default "";
}

Usage Examples:

// Contact with all fields
@Info(
    title = "Customer Service API",
    version = "1.0.0",
    contact = @Contact(
        name = "Customer Service Team",
        url = "https://example.com/support",
        email = "support@example.com"
    )
)

// Contact with name and email only
@Info(
    title = "Internal Tools API", 
    version = "1.2.0",
    contact = @Contact(
        name = "Internal Tools Team",
        email = "internal-tools@company.com"
    )
)

// Individual developer contact
@Info(
    title = "Personal Project API",
    version = "0.1.0",
    contact = @Contact(
        name = "Jane Smith",
        url = "https://janesmith.dev",
        email = "jane@janesmith.dev"
    )
)

@License Annotation

Defines license information for the API including license name and URL. Used within @Info to specify the legal terms under which the API is provided.

/**
 * Defines license information for API
 * Target: ANNOTATION_TYPE  
 * Retention: RUNTIME
 */
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface License {
    /**
     * License name used for the API
     * REQUIRED ATTRIBUTE
     */
    String name();
    
    /**
     * URL to the license used for the API
     * Must be in URL format
     */
    String url() default "";
}

Usage Examples:

// Open source licenses
@Info(
    title = "Open Source API",
    version = "1.0.0",
    license = @License(
        name = "MIT License",
        url = "https://opensource.org/licenses/MIT"
    )
)

@Info(
    title = "Community API",
    version = "2.0.0", 
    license = @License(
        name = "Apache License 2.0",
        url = "https://www.apache.org/licenses/LICENSE-2.0"
    )
)

// Commercial license
@Info(
    title = "Enterprise API",
    version = "3.1.0",
    license = @License(
        name = "Commercial License",
        url = "https://example.com/licenses/commercial"
    )
)

// License name only
@Info(
    title = "Proprietary API",
    version = "1.0.0",
    license = @License(name = "Proprietary")
)

Scheme Enum

Defines the transfer protocols supported by the API. Used within @SwaggerDefinition to specify which protocols (HTTP, HTTPS, WebSocket, etc.) are available.

/**
 * Transfer protocol schemes
 */
enum Scheme {
    /** Default - no specific scheme defined */
    DEFAULT,
    /** HTTP protocol */
    HTTP,  
    /** HTTPS protocol */
    HTTPS,
    /** WebSocket protocol */
    WS,
    /** Secure WebSocket protocol */ 
    WSS
}

Usage Examples:

// HTTPS only (secure)
@SwaggerDefinition(
    schemes = {Scheme.HTTPS},
    host = "secure-api.example.com"
)

// Both HTTP and HTTPS
@SwaggerDefinition(
    schemes = {Scheme.HTTP, Scheme.HTTPS},
    host = "api.example.com"
)

// WebSocket support
@SwaggerDefinition(
    schemes = {Scheme.HTTPS, Scheme.WSS},
    host = "realtime-api.example.com",
    info = @Info(
        title = "Real-time Streaming API",
        version = "1.0.0",
        description = "API with both REST endpoints and WebSocket streaming"
    )
)

// Development environment (HTTP only)
@SwaggerDefinition(
    schemes = {Scheme.HTTP},
    host = "localhost:8080"
)

Integration Example

Here's a complete example showing how all documentation metadata annotations work together:

@SwaggerDefinition(
    info = @Info(
        title = "E-Commerce Platform API",
        version = "2.1.0",
        description = "A comprehensive RESTful API for managing an e-commerce platform. " +
                     "Supports product catalog management, order processing, customer management, " +
                     "and payment processing with full security and monitoring capabilities.",
        termsOfService = "https://ecommerce.example.com/terms",
        contact = @Contact(
            name = "E-Commerce Platform Team",
            url = "https://ecommerce.example.com/support", 
            email = "api-support@ecommerce.example.com"
        ),
        license = @License(
            name = "MIT License",
            url = "https://opensource.org/licenses/MIT"
        ),
        extensions = {
            @Extension(
                name = "x-api-id",
                properties = @ExtensionProperty(name = "value", value = "ecommerce-api-v2")
            )
        }
    ),
    host = "api.ecommerce.example.com",
    basePath = "/v2",
    schemes = {Scheme.HTTPS},
    consumes = {"application/json", "application/xml"},
    produces = {"application/json", "application/xml", "text/csv"},
    tags = {
        @Tag(
            name = "products",
            description = "Product catalog management operations",
            externalDocs = @ExternalDocs(
                value = "Product Management Guide",
                url = "https://docs.ecommerce.example.com/products"
            )
        ),
        @Tag(
            name = "orders", 
            description = "Order processing and fulfillment operations",
            externalDocs = @ExternalDocs(
                value = "Order Processing Documentation", 
                url = "https://docs.ecommerce.example.com/orders"
            )
        ),
        @Tag(
            name = "customers",
            description = "Customer account and profile management",
            externalDocs = @ExternalDocs(
                value = "Customer Management Guide",
                url = "https://docs.ecommerce.example.com/customers"
            )
        )
    },
    externalDocs = @ExternalDocs(
        value = "Complete API Documentation",
        url = "https://docs.ecommerce.example.com"
    )
)
public class ECommerceApiConfiguration {
    // Configuration class for API documentation
}

Best Practices

  1. Always provide meaningful titles and descriptions - Help developers understand the purpose and scope of your API
  2. Include contact information - Make it easy for API consumers to get help or report issues
  3. Specify appropriate licenses - Clearly communicate legal terms for API usage
  4. Use external documentation links - Provide detailed guides and tutorials outside of the API spec
  5. Choose appropriate schemes - Use HTTPS for production APIs, HTTP only for local development
  6. Organize with consistent tags - Group related operations logically for better navigation
  7. Keep descriptions current - Update API metadata when functionality changes
  8. Use semantic versioning - Follow standard versioning practices for the API version
  9. Provide terms of service - Include legal terms for commercial or public APIs
  10. Link to comprehensive documentation - Use externalDocs to reference complete guides and tutorials

Install with Tessl CLI

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

docs

core-api.md

documentation.md

extensions.md

index.md

models.md

parameters.md

responses.md

security.md

tile.json