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
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.swagger.core.v3/swagger-annotations-jakarta@2.2.x
Publish Source
CLI
Badge
tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta badge