or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdcore-annotations.mdindex.mdresponses.mdschema-media.mdsecurity.mdservers-tags.md
tile.json

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

Swagger Core annotations library providing OpenAPI 3.x annotations for Java applications, enabling developers to document REST APIs with metadata annotations

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

To install, run

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

index.mddocs/

Swagger Annotations

Swagger Core annotations library providing OpenAPI 3.x annotations for Java applications, enabling developers to document REST APIs with metadata annotations.

Package Information

The swagger-annotations library is a Maven artifact that provides comprehensive Java annotations for OpenAPI 3.x specification generation.

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.31</version>
</dependency>

Jakarta Namespace Support: Since version 2.1.7, Swagger Core provides parallel artifacts with the -jakarta suffix for Jakarta EE compatibility:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations-jakarta</artifactId>
    <version>2.2.31</version>
</dependency>

Gradle Installation:

implementation 'io.swagger.core.v3:swagger-annotations:2.2.31'

// For Jakarta namespace
implementation 'io.swagger.core.v3:swagger-annotations-jakarta:2.2.31'

Package Details:

  • Group ID: io.swagger.core.v3
  • Artifact ID: swagger-annotations (or swagger-annotations-jakarta)
  • Version: 2.2.31
  • License: Apache License 2.0
  • Java Support: Compatible with both javax and jakarta namespaces

Core Imports

All annotations are located under the io.swagger.v3.oas.annotations package hierarchy:

// Core annotations
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Hidden;

// Schema and media type annotations
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;

// Response annotations
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

// Security annotations
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;

// Parameter annotations
import io.swagger.v3.oas.annotations.parameters.RequestBody;

// Server and tag annotations
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.info.Info;

Basic Usage

API Definition and Operation Documentation

Document your REST API endpoints with comprehensive OpenAPI metadata:

@RestController
@OpenAPIDefinition(
    info = @Info(
        title = "Pet Store API",
        version = "1.0.0",
        description = "A sample API for managing pets"
    ),
    tags = {
        @Tag(name = "pets", description = "Pet operations")
    }
)
public class PetController {
    
    @Operation(
        summary = "Find pet by ID",
        description = "Returns a single pet",
        tags = {"pets"}
    )
    @ApiResponse(
        responseCode = "200",
        description = "Successful operation",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = Pet.class)
        )
    )
    @ApiResponse(
        responseCode = "404", 
        description = "Pet not found"
    )
    @GetMapping("/pets/{id}")
    public Pet getPetById(
        @Parameter(
            description = "ID of pet to return",
            required = true,
            schema = @Schema(type = "integer", format = "int64")
        )
        @PathVariable Long id
    ) {
        return petService.findById(id);
    }
}

Request Body and Schema Documentation

Define request body schemas and validation constraints:

@PostMapping("/pets")
@Operation(summary = "Add a new pet", tags = {"pets"})
@ApiResponse(
    responseCode = "201",
    description = "Pet created successfully",
    content = @Content(schema = @Schema(implementation = Pet.class))
)
public Pet createPet(
    @RequestBody(
        description = "Pet object to be added",
        required = true,
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = CreatePetRequest.class)
        )
    )
    @Valid @org.springframework.web.bind.annotation.RequestBody CreatePetRequest request
) {
    return petService.create(request);
}

@Schema(description = "Pet data model")
public class Pet {
    @Schema(description = "Pet ID", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;
    
    @Schema(description = "Pet name", example = "Fluffy", required = true, maxLength = 50)
    private String name;
    
    @Schema(description = "Pet category", implementation = Category.class)
    private Category category;
    
    @Schema(description = "Pet status", allowableValues = {"available", "pending", "sold"})
    private String status;
    
    // getters and setters
}

Architecture

The swagger-annotations library provides 56 annotations organized into logical categories:

1. Core API Documentation

  • Operation-level annotations for HTTP methods and endpoint documentation
  • Parameter annotations for request parameters, headers, and path variables
  • OpenAPI definition annotations for API-level metadata

2. Schema and Media Types

  • Schema annotations for data model documentation with validation
  • Array schema annotations for collection types
  • Content and media type annotations for request/response body definitions

3. Response Documentation

  • Response annotations for HTTP response documentation
  • Content negotiation support for multiple media types

4. Security Configuration

  • Security scheme annotations for authentication and authorization
  • OAuth2 flow support with comprehensive configuration options
  • Security requirement annotations for operation-level security

5. Server and Metadata

  • Server annotations for API server configuration
  • Tag annotations for logical operation grouping
  • Info annotations for API metadata (version, contact, license)

6. Advanced Features

  • Extension annotations for vendor-specific OpenAPI extensions
  • Callback annotations for asynchronous operation documentation
  • Webhook annotations for event-driven API documentation
  • OpenAPI 3.1 features including enhanced JSON Schema support

Capabilities

Core API Documentation

Document REST API operations with comprehensive metadata including operation IDs, descriptions, tags, and deprecation status. Handle parameter validation, response definitions, and security requirements at the operation level.

@Operation(
    operationId = "getPetById",
    summary = "Find pet by ID",
    description = "Returns a single pet based on the provided ID",
    tags = {"pets"},
    deprecated = false,
    security = @SecurityRequirement(name = "api_key"),
    responses = {
        @ApiResponse(responseCode = "200", description = "Successful operation"),
        @ApiResponse(responseCode = "404", description = "Pet not found")
    }
)

Core Annotations

Schema and Media Type Documentation

Define comprehensive data schemas with validation constraints, type information, and example values. Support for complex object hierarchies, arrays, and polymorphic types.

@Schema(
    description = "Pet category information",
    required = true,
    example = "{ \"id\": 1, \"name\": \"Dogs\" }",
    minProperties = 1,
    maxProperties = 10
)
@ArraySchema(
    arraySchema = @Schema(description = "List of pets"),
    schema = @Schema(implementation = Pet.class),
    minItems = 0,
    maxItems = 100,
    uniqueItems = true
)

Schema and Media Types

Response Documentation

Document API responses with status codes, headers, content types, and schema definitions. Support for multiple response scenarios and content negotiation.

@ApiResponses({
    @ApiResponse(
        responseCode = "200",
        description = "Successful operation",
        headers = @Header(name = "X-Rate-Limit", description = "Request limit"),
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = Pet.class)
        )
    ),
    @ApiResponse(responseCode = "400", description = "Invalid request")
})

Response Documentation

Security Configuration

Configure authentication and authorization schemes including API keys, OAuth2, OpenID Connect, and mutual TLS. Define security requirements at API and operation levels.

@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    description = "JWT token authentication"
)
@SecurityRequirement(name = "bearerAuth", scopes = {"read", "write"})

Security Configuration

Server and Tag Management

Configure API servers with variable URL templates and define logical groupings of operations with tags and comprehensive metadata.

@Server(
    url = "https://{environment}.petstore.io/v1",
    description = "Pet Store API server",
    variables = @ServerVariable(
        name = "environment",
        description = "Server environment",
        defaultValue = "api",
        allowableValues = {"api", "staging", "dev"}
    )
)
@Tag(name = "pets", description = "Everything about your pets")

Servers and Tags

Advanced Features

Leverage OpenAPI extensions, callback definitions for asynchronous operations, webhook documentation, and OpenAPI 3.1 enhanced features including conditional schemas and improved validation.

@Extension(name = "x-custom-property", properties = {
    @ExtensionProperty(name = "feature", value = "enabled"),
    @ExtensionProperty(name = "version", value = "1.0")
})
@Callback(
    name = "statusCallback",
    callbackUrlExpression = "{$request.body#/callbackUrl}",
    operation = @Operation(summary = "Status update callback")
)
@Webhook(
    name = "petUpdated",
    operation = @Operation(
        summary = "Pet update notification",
        requestBody = @RequestBody(
            content = @Content(schema = @Schema(implementation = PetUpdateEvent.class))
        )
    )
)

Advanced Features

Integration Patterns

Spring Boot Integration

The annotations integrate seamlessly with Spring Boot applications and Spring MVC controllers:

@RestController
@RequestMapping("/api/v1")
@Tag(name = "user-controller", description = "User management operations")
public class UserController {
    
    @GetMapping("/users")
    @Operation(summary = "Get all users", tags = {"users"})
    public List<User> getAllUsers(
        @Parameter(description = "Page number", example = "0")
        @RequestParam(defaultValue = "0") int page,
        
        @Parameter(description = "Page size", example = "20")
        @RequestParam(defaultValue = "20") int size
    ) {
        return userService.findAll(page, size);
    }
}

JAX-RS Integration

Compatible with JAX-RS applications for comprehensive REST API documentation:

@Path("/pets")
@Tag(name = "pets")
public class PetResource {
    
    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    @Operation(summary = "Get pet by ID")
    public Response getPet(
        @Parameter(description = "Pet ID") @PathParam("id") Long id
    ) {
        Pet pet = petService.findById(id);
        return Response.ok(pet).build();
    }
}

Validation Integration

Works with Bean Validation (JSR 303/349/380) annotations for comprehensive validation documentation:

@Schema(description = "User registration request")
public class UserRegistrationRequest {
    @NotBlank
    @Size(min = 2, max = 50)
    @Schema(description = "User's first name", example = "John", minLength = 2, maxLength = 50)
    private String firstName;
    
    @Email
    @NotBlank
    @Schema(description = "User's email address", format = "email", example = "john@example.com")
    private String email;
    
    @Valid
    @Schema(description = "User's address information")
    private Address address;
}