or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

callbacks.mdcore-annotations.mdenums.mdindex.mdlinks.mdresponses.mdschema-media.mdsecurity.mdserver-info.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.swagger.core.v3/swagger-annotations-jakarta@2.2.x

To install, run

npx @tessl/cli install tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta@2.2.0

index.mddocs/

Swagger Annotations Jakarta

Swagger Annotations Jakarta provides a comprehensive set of Java annotations for defining OpenAPI 3.0 and 3.1 specifications in Jakarta EE environments. The library contains 56 annotation interfaces and 5 enums that enable developers to document REST APIs directly in their source code, supporting all major OpenAPI specification features.

Package Information

  • Package Name: swagger-annotations-jakarta
  • Package Type: maven
  • Group ID: io.swagger.core.v3
  • Artifact ID: swagger-annotations-jakarta
  • Version: 2.2.31
  • Language: Java
  • Installation: Add to your pom.xml:
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations-jakarta</artifactId>
    <version>2.2.31</version>
</dependency>

Core Imports

import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.info.*;
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.parameters.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.security.*;

Basic Usage

import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.info.*;
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.parameters.*;
import io.swagger.v3.oas.annotations.responses.*;
import jakarta.ws.rs.*;

@OpenAPIDefinition(
    info = @Info(
        title = "User API",
        version = "1.0.0",
        description = "API for managing user accounts"
    )
)
public class UserApplication {}

@Path("/users")
public class UserResource {
    
    @GET
    @Operation(
        summary = "Get user by ID",
        description = "Retrieves a user account by their unique identifier"
    )
    @ApiResponse(
        responseCode = "200",
        description = "User found",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = User.class)
        )
    )
    @ApiResponse(responseCode = "404", description = "User not found")
    public Response getUser(
        @Parameter(description = "User ID", required = true)
        @PathParam("id") Long id
    ) {
        // Implementation
    }
    
    @POST
    @Operation(summary = "Create new user")
    @ApiResponse(responseCode = "201", description = "User created")
    public Response createUser(
        @RequestBody(
            description = "User data",
            required = true,
            content = @Content(schema = @Schema(implementation = CreateUserRequest.class))
        )
        CreateUserRequest request
    ) {
        // Implementation
    }
}

@Schema(description = "User account information")
public class User {
    @Schema(description = "Unique user identifier", example = "123")
    private Long id;
    
    @Schema(description = "User's email address", example = "user@example.com")
    private String email;
    
    @Schema(description = "User's display name", example = "John Doe")
    private String name;
}

Architecture

Swagger Annotations Jakarta is built around several key components:

  • Core Annotations: Primary annotations for defining operations, parameters, and OpenAPI metadata
  • Schema System: Comprehensive schema definition with validation, typing, and composition features
  • Security Framework: OAuth2, API keys, HTTP authentication, and custom security schemes
  • Response Management: Structured response definitions with content types, headers, and status codes
  • Server Configuration: Multi-environment server definitions with templated variables
  • Jakarta EE Compatibility: Automatic transformation from javax.* to jakarta.* for modern Jakarta EE applications

Capabilities

Core API Documentation

Essential annotations for documenting REST operations, parameters, and API structure. These form the foundation of OpenAPI documentation.

@Operation(
    summary = "Brief operation description",
    description = "Detailed operation description",
    operationId = "uniqueOperationId",
    tags = {"tag1", "tag2"},
    parameters = {@Parameter(...)},
    responses = {@ApiResponse(...)},
    security = {@SecurityRequirement(...)}
)

@Parameter(
    name = "paramName",
    in = ParameterIn.QUERY,
    description = "Parameter description",
    required = true,
    schema = @Schema(type = "string")
)

@OpenAPIDefinition(
    info = @Info(title = "API Title", version = "1.0.0"),
    servers = {@Server(url = "https://api.example.com")},
    security = {@SecurityRequirement(...)}
)

Core Annotations

Schema and Media Types

Comprehensive schema definition system supporting OpenAPI 3.0 and 3.1 features including validation, composition, and conditional schemas.

@Schema(
    description = "Schema description",
    implementation = MyClass.class,
    required = true,
    example = "example value",
    pattern = "regex pattern",
    minimum = "0",
    maximum = "100"
)

@Content(
    mediaType = "application/json",
    schema = @Schema(implementation = ResponseDto.class),
    examples = {@ExampleObject(...)}
)

@ArraySchema(
    schema = @Schema(implementation = String.class),
    minItems = 1,
    maxItems = 10,
    uniqueItems = true
)

Schema and Media Types

Security Configuration

Complete security scheme definitions supporting OAuth2 flows, API keys, HTTP authentication, and OpenID Connect.

@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)

@SecurityRequirement(
    name = "bearerAuth",
    scopes = {"read:users", "write:users"}
)

@OAuthFlows(
    authorizationCode = @OAuthFlow(
        authorizationUrl = "https://auth.example.com/oauth/authorize",
        tokenUrl = "https://auth.example.com/oauth/token",
        scopes = {@OAuthScope(name = "read", description = "Read access")}
    )
)

Security Configuration

Response Definitions

Structured response documentation with status codes, content types, headers, and linking between operations.

@ApiResponse(
    responseCode = "200",
    description = "Success response",
    content = {@Content(
        mediaType = "application/json",
        schema = @Schema(implementation = ResponseDto.class)
    )},
    headers = {@Header(name = "X-Rate-Limit", schema = @Schema(type = "integer"))},
    links = {@Link(name = "self", operationId = "getUserById")}
)

@RequestBody(
    description = "Request payload",
    required = true,
    content = {@Content(
        mediaType = "application/json",
        schema = @Schema(implementation = CreateUserRequest.class)
    )}
)

Response Management

Server and API Information

Server definitions, API metadata, contact information, and external documentation configuration.

@Server(
    url = "https://api.{environment}.example.com",
    description = "Main API server",
    variables = {@ServerVariable(
        name = "environment",
        defaultValue = "prod",
        allowableValues = {"dev", "staging", "prod"}
    )}
)

@Info(
    title = "User Management API",
    version = "2.1.0",
    description = "Complete user management system",
    contact = @Contact(name = "API Team", email = "api@example.com"),
    license = @License(name = "MIT", url = "https://opensource.org/licenses/MIT")
)

@Tag(
    name = "users",
    description = "User management operations",
    externalDocs = @ExternalDocumentation(
        description = "User guide",
        url = "https://docs.example.com/users"
    )
)

Server and Info Configuration

Callbacks and Webhooks

Advanced callback operations for asynchronous API interactions and webhook definitions supporting OpenAPI 3.1 features.

@Callback(
    name = "userStatusUpdate",
    callbackUrlExpression = "{$request.body#/callbackUrl}",
    operation = @Operation(
        method = "POST",
        summary = "User status changed notification"
    )
)

@Webhook(
    name = "userCreated",
    operation = @Operation(summary = "User created webhook")
)

Callbacks and Webhooks

Links and Operation References

Define relationships between operations and enable workflow documentation with parameter passing between linked operations.

@Link(
    name = "getUserById",
    operationId = "getUserById",
    parameters = @LinkParameter(name = "userId", expression = "$response.body#/id")
)

@LinkParameter(
    name = "userId",
    expression = "$response.body#/id"
)

Links and References

Enums and Constants

Complete reference for all enumeration types used throughout the annotation system including parameter styles, security schemes, and validation options.

enum ParameterIn { QUERY, PATH, HEADER, COOKIE, DEFAULT }
enum ParameterStyle { FORM, SIMPLE, MATRIX, LABEL, SPACEDELIMITED, PIPEDELIMITED, DEEPOBJECT, DEFAULT }
enum SecuritySchemeType { APIKEY, HTTP, OAUTH2, OPENIDCONNECT, MUTUALTLS, DEFAULT }
enum SecuritySchemeIn { HEADER, QUERY, COOKIE, DEFAULT }
enum Explode { TRUE, FALSE, DEFAULT }

Enums Reference

Jakarta EE Transformation

This library is automatically generated from the original swagger-annotations using Eclipse Transformer:

  • Original: Uses javax.* imports (Java EE)
  • Jakarta Version: Uses jakarta.* imports (Jakarta EE)
  • API Compatibility: Identical API surface - same annotations, attributes, and functionality
  • Migration Path: Seamless upgrade from javax-based applications to Jakarta EE

Integration Frameworks

Compatible with major Jakarta EE REST frameworks:

  • Jakarta REST (JAX-RS): Jersey, RESTEasy, Apache CXF
  • Spring Boot: With springdoc-openapi integration
  • MicroProfile OpenAPI: SmallRye, Open Liberty implementations
  • Quarkus: Built-in OpenAPI support
  • Helidon: Native integration with OpenAPI specification generation

OpenAPI 3.1 Features

Extensive support for OpenAPI 3.1 including:

  • Webhooks: @Webhook and @Webhooks annotations
  • Dependent Schemas: @DependentSchema and conditional validation
  • Pattern Properties: @PatternProperty for regex-based schema matching
  • Enhanced Schema: Additional validation keywords and composition features
  • Improved Security: Extended security scheme options