CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta

Jakarta EE compatible OpenAPI 3.x annotations for defining REST API specifications

—

Pending
Overview
Eval results
Files

server-info.mddocs/

Server and API Information

Server definitions, API metadata, contact information, external documentation, and tags configuration. This system provides comprehensive API information management including multi-environment server configuration, detailed API metadata, and organizational features.

Capabilities

Server Configuration

Defines server connectivity information with URL templates and environment variables.

/**
 * Defines server connectivity information
 * Applied to: TYPE, METHOD (for operation-specific servers)
 * Repeatable: Yes
 */
@Server(
    url = "https://api.{environment}.example.com",  // Server URL with variables (required)
    description = "Main API server",                // Server description
    variables = {                                   // URL template variables
        @ServerVariable(
            name = "environment",
            defaultValue = "prod",
            allowableValues = {"dev", "staging", "prod"},
            description = "Deployment environment"
        ),
        @ServerVariable(
            name = "version",
            defaultValue = "v1", 
            allowableValues = {"v1", "v2"},
            description = "API version"
        )
    },
    extensions = {@Extension(...)}                  // Custom extensions
)

/**
 * Defines server URL template variables
 */
@ServerVariable(
    name = "environment",                           // Variable name (required)
    defaultValue = "prod",                          // Default value (required)
    allowableValues = {"dev", "staging", "prod"},   // Allowed values (optional)
    description = "Environment identifier",         // Variable description
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// Single server
@OpenAPIDefinition(
    info = @Info(title = "API", version = "1.0"),
    servers = @Server(
        url = "https://api.example.com",
        description = "Production server"
    )
)

// Multiple servers with environments
@OpenAPIDefinition(
    info = @Info(title = "Multi-Environment API", version = "2.0"),
    servers = {
        @Server(
            url = "https://api.{environment}.example.com",
            description = "Environment-specific server",
            variables = @ServerVariable(
                name = "environment",
                defaultValue = "prod",
                allowableValues = {"dev", "staging", "prod"},
                description = "Deployment environment"
            )
        ),
        @Server(
            url = "https://localhost:{port}",
            description = "Local development server",
            variables = @ServerVariable(
                name = "port",
                defaultValue = "8080",
                allowableValues = {"8080", "3000", "9000"},
                description = "Port number"
            )
        )
    }
)

// Regional servers
@OpenAPIDefinition(
    servers = {
        @Server(
            url = "https://api-{region}.example.com",
            description = "Regional API server",
            variables = @ServerVariable(
                name = "region",
                defaultValue = "us-east",
                allowableValues = {"us-east", "us-west", "eu-central", "ap-southeast"},
                description = "Geographic region"
            )
        ),
        @Server(
            url = "https://api.example.com",
            description = "Global load balancer"
        )
    }
)

// Operation-specific server override
@POST
@Path("/special")
@Operation(
    summary = "Special operation using different server",
    servers = @Server(
        url = "https://special-api.example.com",
        description = "Specialized processing server"
    )
)
public Response specialOperation() {}

// Complex server variables
@Server(
    url = "https://{customer}.{environment}.example.com:{port}/{basePath}",
    description = "Multi-tenant server with custom base path",
    variables = {
        @ServerVariable(
            name = "customer",
            defaultValue = "default",
            description = "Customer tenant identifier"
        ),
        @ServerVariable(
            name = "environment", 
            defaultValue = "prod",
            allowableValues = {"dev", "staging", "prod"}
        ),
        @ServerVariable(
            name = "port",
            defaultValue = "443",
            allowableValues = {"80", "443", "8443"}
        ),
        @ServerVariable(
            name = "basePath",
            defaultValue = "api/v1",
            description = "API base path"
        )
    }
)

Servers Container

Container for multiple server definitions.

/**
 * Container for multiple Server annotations
 */
@Servers({
    @Server(url = "https://api.example.com", description = "Production"),
    @Server(url = "https://staging-api.example.com", description = "Staging"),
    @Server(url = "http://localhost:8080", description = "Development")
})

API Information

Comprehensive API metadata including title, version, description, contact, and license information.

/**
 * Defines API metadata information
 * Applied to: within OpenAPIDefinition
 */
@Info(
    title = "User Management API",                  // API title (required)
    version = "2.1.0",                             // API version (required)
    description = "Complete user management system with authentication and authorization", // API description
    summary = "User management and authentication API", // Short API summary (OpenAPI 3.1)
    termsOfService = "https://example.com/terms",   // Terms of service URL
    contact = @Contact(...),                        // Contact information
    license = @License(...),                        // License information
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// Basic API info
@Info(
    title = "E-Commerce API",
    version = "3.0.0",
    description = "RESTful API for e-commerce operations including products, orders, and payments"
)

// Complete API info with contact and license
@Info(
    title = "Enterprise User API",
    version = "2.5.1",
    description = """
        Comprehensive user management API providing:
        - User account creation and management
        - Authentication and authorization
        - Role-based access control
        - Profile management
        - Activity tracking
        """,
    summary = "Enterprise-grade user management API",
    termsOfService = "https://example.com/api/terms",
    contact = @Contact(
        name = "API Support Team",
        email = "api-support@example.com",
        url = "https://example.com/support"
    ),
    license = @License(
        name = "Apache License 2.0",
        url = "https://www.apache.org/licenses/LICENSE-2.0.html",
        identifier = "Apache-2.0"
    ),
    extensions = {
        @Extension(
            name = "x-api-category",
            properties = @ExtensionProperty(name = "category", value = "user-management")
        ),
        @Extension(
            name = "x-maturity-level",
            properties = @ExtensionProperty(name = "level", value = "stable")
        )
    }
)

Contact Information

Defines contact information for the API.

/**
 * Defines contact information for the API
 * Applied to: within Info annotation
 */
@Contact(
    name = "API Support Team",                      // Contact name
    email = "support@example.com",                  // Contact email
    url = "https://example.com/support",           // Contact URL
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// Basic contact
@Contact(
    name = "Development Team",
    email = "dev@example.com"
)

// Complete contact with support portal
@Contact(
    name = "API Support",
    email = "api-support@example.com",
    url = "https://support.example.com/api",
    extensions = @Extension(
        name = "x-support-hours",
        properties = {
            @ExtensionProperty(name = "timezone", value = "UTC"),
            @ExtensionProperty(name = "hours", value = "24/7"),
            @ExtensionProperty(name = "sla", value = "4-hour response")
        }
    )
)

// Team contact with multiple channels
@Contact(
    name = "Platform Team",
    email = "platform@example.com",
    url = "https://example.com/platform-team",
    extensions = {
        @Extension(
            name = "x-contact-channels",
            properties = {
                @ExtensionProperty(name = "slack", value = "#platform-support"),
                @ExtensionProperty(name = "phone", value = "+1-555-0123"),
                @ExtensionProperty(name = "hours", value = "9 AM - 5 PM EST")
            }
        )
    }
)

License Information

Defines license information for the API.

/**
 * Defines license information for the API
 * Applied to: within Info annotation
 */
@License(
    name = "Apache License 2.0",                   // License name (required)
    url = "https://www.apache.org/licenses/LICENSE-2.0.html", // License URL
    identifier = "Apache-2.0",                     // SPDX license identifier (OpenAPI 3.1)
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// MIT License
@License(
    name = "MIT License",
    url = "https://opensource.org/licenses/MIT",
    identifier = "MIT"
)

// Apache License with additional info
@License(
    name = "Apache License, Version 2.0",
    url = "https://www.apache.org/licenses/LICENSE-2.0.html",
    identifier = "Apache-2.0",
    extensions = @Extension(
        name = "x-license-info",
        properties = {
            @ExtensionProperty(name = "attribution", value = "Required"),
            @ExtensionProperty(name = "commercial-use", value = "Allowed"),
            @ExtensionProperty(name = "modification", value = "Allowed")
        }
    )
)

// Custom license
@License(
    name = "Custom Enterprise License",
    url = "https://example.com/licenses/enterprise",
    extensions = @Extension(
        name = "x-license-type",
        properties = @ExtensionProperty(name = "type", value = "proprietary")
    )
)

// GPL License
@License(
    name = "GNU General Public License v3.0",
    url = "https://www.gnu.org/licenses/gpl-3.0.html",
    identifier = "GPL-3.0"
)

Tag Definitions

Defines tags for logical grouping of operations with metadata and external documentation.

/**
 * Defines tag for operation grouping
 * Applied to: TYPE (global tags), METHOD (operation tags)
 * Repeatable: Yes
 */
@Tag(
    name = "users",                                 // Tag name (required)
    description = "User management operations",     // Tag description
    externalDocs = @ExternalDocumentation(          // External documentation
        description = "User Management Guide",
        url = "https://docs.example.com/users"
    ),
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// Global tags definition
@OpenAPIDefinition(
    info = @Info(title = "API", version = "1.0"),
    tags = {
        @Tag(
            name = "users",
            description = "User account management and authentication",
            externalDocs = @ExternalDocumentation(
                description = "User Guide",
                url = "https://docs.example.com/user-guide"
            )
        ),
        @Tag(
            name = "products",
            description = "Product catalog and inventory management",
            externalDocs = @ExternalDocumentation(
                description = "Product Management Guide", 
                url = "https://docs.example.com/products"
            )
        ),
        @Tag(
            name = "orders",
            description = "Order processing and fulfillment"
        ),
        @Tag(
            name = "admin",
            description = "Administrative operations",
            extensions = @Extension(
                name = "x-audience",
                properties = @ExtensionProperty(name = "audience", value = "internal")
            )
        )
    }
)

// Operation with multiple tags
@GET
@Path("/user/{id}/orders")
@Operation(
    summary = "Get user orders",
    tags = {"users", "orders"}
)
public Response getUserOrders(@PathParam("id") Long userId) {}

// Tag with detailed metadata
@Tag(
    name = "authentication",
    description = "Authentication and authorization endpoints",
    externalDocs = @ExternalDocumentation(
        description = "Authentication Guide",
        url = "https://docs.example.com/auth"
    ),
    extensions = {
        @Extension(
            name = "x-tag-metadata",
            properties = {
                @ExtensionProperty(name = "stability", value = "stable"),
                @ExtensionProperty(name = "audience", value = "public"),
                @ExtensionProperty(name = "rate-limit", value = "strict")
            }
        )
    }
)

Tags Container

Container for multiple tag definitions.

/**
 * Container for multiple Tag annotations
 */
@Tags({
    @Tag(name = "users", description = "User operations"),
    @Tag(name = "products", description = "Product operations"),
    @Tag(name = "orders", description = "Order operations"),
    @Tag(name = "admin", description = "Administrative operations")
})

External Documentation

Defines references to external documentation for various API elements.

/**
 * Defines external documentation reference
 * Applied to: various annotation elements
 */
@ExternalDocumentation(
    description = "Complete API documentation",     // Description (required)
    url = "https://docs.example.com/api",          // Documentation URL (required)
    extensions = {@Extension(...)}                  // Custom extensions
)

Usage Examples:

// API-level external docs
@OpenAPIDefinition(
    info = @Info(title = "API", version = "1.0"),
    externalDocs = @ExternalDocumentation(
        description = "Complete API Documentation and Tutorials",
        url = "https://docs.example.com/api/v1"
    )
)

// Operation-specific external docs
@Operation(
    summary = "Complex data processing",
    externalDocs = @ExternalDocumentation(
        description = "Data Processing Algorithm Details",
        url = "https://docs.example.com/algorithms/data-processing"
    )
)

// Tag external docs
@Tag(
    name = "advanced",
    description = "Advanced operations requiring special configuration",
    externalDocs = @ExternalDocumentation(
        description = "Advanced Features Configuration Guide",
        url = "https://docs.example.com/advanced-config",
        extensions = @Extension(
            name = "x-doc-type",
            properties = @ExtensionProperty(name = "type", value = "tutorial")
        )
    )
)

// Schema external docs  
@Schema(
    description = "Complex data structure",
    externalDocs = @ExternalDocumentation(
        description = "Data Structure Specification",
        url = "https://specs.example.com/data-structures/v2"
    )
)

Configuration Patterns

Multi-Environment Setup

@OpenAPIDefinition(
    info = @Info(
        title = "Multi-Environment API",
        version = "1.0.0",
        description = "API available across multiple environments"
    ),
    servers = {
        @Server(
            url = "https://api.{environment}.{region}.example.com",
            description = "Regional servers across environments",
            variables = {
                @ServerVariable(
                    name = "environment",
                    defaultValue = "prod",
                    allowableValues = {"dev", "staging", "prod"},
                    description = "Deployment environment"
                ),
                @ServerVariable(
                    name = "region",
                    defaultValue = "us-east",
                    allowableValues = {"us-east", "us-west", "eu-central", "ap-southeast"},
                    description = "Geographic region"
                )
            }
        ),
        @Server(
            url = "http://localhost:{port}",
            description = "Local development",
            variables = @ServerVariable(
                name = "port",
                defaultValue = "8080",
                description = "Local port number"
            )
        )
    }
)

Complete API Metadata

@OpenAPIDefinition(
    info = @Info(
        title = "Enterprise Resource Management API",
        version = "3.2.1",
        summary = "Comprehensive ERM system API",
        description = """
            Enterprise Resource Management API providing comprehensive functionality for:
            
            - **User Management**: Account creation, authentication, role management
            - **Resource Management**: Asset tracking, allocation, reporting
            - **Financial Operations**: Budgeting, expense tracking, financial reporting
            - **Analytics**: Real-time dashboards, custom reports, data export
            
            This API follows RESTful principles and supports JSON and XML formats.
            All endpoints require authentication via JWT tokens or API keys.
            """,
        termsOfService = "https://example.com/api/terms",
        contact = @Contact(
            name = "Enterprise API Support",
            email = "enterprise-api@example.com",
            url = "https://support.example.com/enterprise-api"
        ),
        license = @License(
            name = "Enterprise License Agreement",
            url = "https://example.com/licenses/enterprise",
            identifier = "Enterprise-1.0"
        ),
        extensions = {
            @Extension(
                name = "x-api-metadata",
                properties = {
                    @ExtensionProperty(name = "category", value = "enterprise"),
                    @ExtensionProperty(name = "maturity", value = "stable"),
                    @ExtensionProperty(name = "sla", value = "99.9%"),
                    @ExtensionProperty(name = "support-tier", value = "premium")
                }
            )
        }
    ),
    servers = {
        @Server(
            url = "https://enterprise-api.{region}.example.com",
            description = "Enterprise regional servers",
            variables = @ServerVariable(
                name = "region",
                defaultValue = "us",
                allowableValues = {"us", "eu", "ap"},
                description = "Service region"
            )
        )
    },
    tags = {
        @Tag(
            name = "users",
            description = "User account and authentication management",
            externalDocs = @ExternalDocumentation(
                description = "User Management Guide",
                url = "https://docs.example.com/enterprise/users"
            )
        ),
        @Tag(
            name = "resources",
            description = "Resource allocation and tracking",
            externalDocs = @ExternalDocumentation(
                description = "Resource Management Guide",
                url = "https://docs.example.com/enterprise/resources"
            )
        ),
        @Tag(
            name = "analytics",
            description = "Reporting and analytics endpoints",
            extensions = @Extension(
                name = "x-feature-flag",
                properties = @ExtensionProperty(name = "requires-premium", value = "true")
            )
        )
    },
    externalDocs = @ExternalDocumentation(
        description = "Complete Enterprise API Documentation",
        url = "https://docs.example.com/enterprise-api"
    )
)

Versioned API Configuration

@OpenAPIDefinition(
    info = @Info(
        title = "Versioned API",
        version = "2.0.0",
        description = "API with version-specific servers and features"
    ),
    servers = {
        @Server(
            url = "https://api.example.com/v{version}",
            description = "Versioned API endpoint",
            variables = @ServerVariable(
                name = "version", 
                defaultValue = "2",
                allowableValues = {"1", "2"},
                description = "API version"
            )
        ),
        @Server(
            url = "https://v{version}.api.example.com",
            description = "Version-specific subdomain",
            variables = @ServerVariable(
                name = "version",
                defaultValue = "2",
                allowableValues = {"1", "2"}
            )
        )
    }
)

Install with Tessl CLI

npx tessl i tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta

docs

callbacks.md

core-annotations.md

enums.md

index.md

links.md

responses.md

schema-media.md

security.md

server-info.md

tile.json