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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Swagger Annotations

Name: tessl/maven-io-swagger-core-v3--swagger-annotations
Author: tessl

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;
}