or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

core-api.md documentation.md extensions.md index.md models.md parameters.md responses.md security.md

tile.json

tessl/maven-io-swagger--swagger-annotations

Java annotations for defining Swagger API documentation and OpenAPI specification metadata

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/io.swagger/swagger-annotations@1.6.x

To install, run

npx @tessl/cli install tessl/maven-io-swagger--swagger-annotations@1.6.0

Swagger Annotations

Swagger Annotations provides a comprehensive set of Java annotations for defining and documenting REST APIs using the OpenAPI/Swagger specification. These annotations allow developers to declaratively describe their API endpoints, data models, parameters, and responses, enabling automatic generation of OpenAPI specification documents for API documentation, client code generation, and interactive API exploration.

Package Information

Package Name: swagger-annotations
Package Type: Maven
Language: Java
Group ID: io.swagger
Artifact ID: swagger-annotations
Installation: <dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.6.15</version></dependency>

Core Imports

import io.swagger.annotations.*;

For specific annotations:

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

Basic Usage

import io.swagger.annotations.*;

@Api(tags = "users", description = "User management operations")
@Path("/users")
public class UserController {

    @ApiOperation(
        value = "Get user by ID",
        notes = "Returns a single user based on the provided ID",
        response = User.class
    )
    @GET
    @Path("/{id}")
    public Response getUser(
        @ApiParam(value = "User ID", required = true, example = "123")
        @PathParam("id") Long id
    ) {
        // implementation
    }

    @ApiOperation(value = "Create new user", response = User.class)
    @POST
    public Response createUser(
        @ApiParam(value = "User data", required = true)
        User user
    ) {
        // implementation
    }
}

@ApiModel(description = "User entity")
public class User {
    @ApiModelProperty(value = "User ID", example = "123", readOnly = true)
    private Long id;
    
    @ApiModelProperty(value = "User name", required = true, example = "John Doe")
    private String name;
    
    @ApiModelProperty(value = "Email address", required = true, example = "john@example.com")
    private String email;
}

Architecture

Swagger Annotations is organized around several key annotation categories:

Core API Annotations: Define API-level and operation-level metadata (@Api, @ApiOperation)
Parameter Annotations: Document API parameters and inputs (@ApiParam, @ApiImplicitParam)
Model Annotations: Describe data models and their properties (@ApiModel, @ApiModelProperty)
Response Annotations: Document API responses and headers (@ApiResponse, @ResponseHeader)
Security Annotations: Define authentication and authorization requirements
Documentation Annotations: Provide additional documentation metadata
Extension System: Support for custom properties and extensions

Capabilities

Core API Documentation

Essential annotations for marking and documenting API resources and operations. These form the foundation of Swagger documentation.

@Target(ElementType.TYPE)
@interface Api {
    String value() default "";
    String[] tags() default "";
    String produces() default "";
    String consumes() default "";
    String protocols() default "";
    Authorization[] authorizations() default @Authorization(value = "");
    boolean hidden() default false;
}

@Target({ElementType.METHOD, ElementType.TYPE})
@interface ApiOperation {
    String value(); // Required - operation summary
    String notes() default "";
    String[] tags() default "";
    Class<?> response() default Void.class;
    String responseContainer() default "";
    String responseReference() default "";
    String httpMethod() default "";  
    int position() default 0; // @deprecated
    String nickname() default "";
    String produces() default "";
    String consumes() default "";
    String protocols() default "";
    Authorization[] authorizations() default @Authorization(value = "");
    boolean hidden() default false;
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
    int code() default 200;
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
    boolean ignoreJsonView() default false;
}

Core API Documentation

Parameter Documentation

Annotations for documenting API parameters, including path parameters, query parameters, and request bodies.

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@interface ApiParam {
    String name() default "";
    String value() default "";
    String defaultValue() default "";
    String allowableValues() default "";
    boolean required() default false;
    String access() default "";
    boolean allowMultiple() default false;
    boolean hidden() default false;
    String example() default "";
    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
    String type() default "";
    String format() default "";
    boolean allowEmptyValue() default false;
    boolean readOnly() default false;
    String collectionFormat() default "";
}

@Target({ElementType.METHOD, ElementType.TYPE})
@interface ApiImplicitParam {
    String name() default "";
    String value() default "";
    String defaultValue() default "";
    String allowableValues() default "";
    boolean required() default false;
    String dataType() default "";
    String dataTypeClass() default "";
    String paramType() default "";
    String access() default "";
    boolean allowMultiple() default false;
    String format() default "";
    boolean allowEmptyValue() default false;
    boolean readOnly() default false;
    String collectionFormat() default "";
    String example() default "";
}

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@interface ApiImplicitParams {
    ApiImplicitParam[] value();
}

Parameter Documentation

Data Model Documentation

Annotations for documenting data models, their properties, and relationships.

@Target({ElementType.TYPE})
@interface ApiModel {
    String value() default "";
    String description() default "";
    Class<?> parent() default Void.class;
    String discriminator() default "";
    Class<?>[] subTypes() default {};
    String reference() default "";
}

@Target({ElementType.METHOD, ElementType.FIELD})  
@interface ApiModelProperty {
    String value() default "";
    String name() default "";
    String allowableValues() default "";
    String access() default "";
    String notes() default "";
    String dataType() default "";
    boolean required() default false;
    int position() default 0;
    boolean hidden() default false;
    String example() default "";
    boolean readOnly() default false; // @deprecated
    AccessMode accessMode() default AccessMode.AUTO;
    String reference() default "";
    boolean allowEmptyValue() default false;
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
}

Data Model Documentation

Response Documentation

Annotations for documenting API responses, status codes, and response headers.

@Target({ElementType.METHOD, ElementType.TYPE})
@interface ApiResponse {
    int code();
    String message();
    Class<?> response() default Void.class;
    String reference() default "";
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
    String responseContainer() default "";
}

@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.TYPE})
@interface ApiResponses {
    ApiResponse[] value();
}

@Target(ElementType.ANNOTATION_TYPE)
@interface ResponseHeader {
    String name();
    String description() default "";
    Class<?> response();
    String responseContainer() default "";
}

Response Documentation

Security Configuration

Annotations for defining authentication and authorization requirements for APIs.

@Target(ElementType.ANNOTATION_TYPE)
@interface Authorization {
    String value();
    AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = "");
}

@Target(ElementType.ANNOTATION_TYPE)
@interface AuthorizationScope {
    String scope();
    String description() default "";
}

@Target(ElementType.ANNOTATION_TYPE)
@interface SecurityDefinition {
    ApiKeyAuthDefinition[] apiKeyAuthDefintions() default @ApiKeyAuthDefinition(key = "", name = "", in = ApiKeyLocation.HEADER);
    BasicAuthDefinition[] basicAuthDefinions() default @BasicAuthDefinition(key = "");
    OAuth2Definition[] oAuth2Definitions() default @OAuth2Definition(key = "", authorizationUrl = "");
}

Security Configuration

Documentation Metadata

Additional annotations for providing documentation metadata and external references.

@Target({ElementType.TYPE, ElementType.METHOD})
@interface Tag {
    String name();
    String description() default "";
    ExternalDocs externalDocs() default @ExternalDocs(value = "", url = "");
}

@Target(ElementType.ANNOTATION_TYPE)
@interface ExternalDocs {
    String value() default "";
    String url();
}

@Target(ElementType.TYPE)
@interface SwaggerDefinition {
    Info info() default @Info(title = "", version = "");
    String host() default "";
    String basePath() default "";
    Scheme[] schemes() default {};
    String[] consumes() default {};
    String[] produces() default {};
    Tag[] tags() default {};
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
}

Documentation Metadata

Extension System

Annotations for adding custom properties and extensions to the OpenAPI specification.

@Target(ElementType.ANNOTATION_TYPE)
@interface Extension {
    String name() default "";
    ExtensionProperty[] properties();
}

@Target(ElementType.ANNOTATION_TYPE)
@interface ExtensionProperty {
    String name();
    String value();
}

@Target(ElementType.ANNOTATION_TYPE)
@interface Example {
    ExampleProperty[] value();
}

@Target(ElementType.ANNOTATION_TYPE)
@interface ExampleProperty {
    String mediaType() default "";
    String value();
}

Extension System

Types

ApiKeyAuthDefinition with ApiKeyLocation Enum

@Target(ElementType.ANNOTATION_TYPE)
@interface ApiKeyAuthDefinition {
    String key();
    String description() default "";
    ApiKeyLocation in();
    String name();
    
    enum ApiKeyLocation {
        HEADER, QUERY;
        
        public static ApiKeyLocation forValue(String value);
        public String toValue();
    }
}

OAuth2Definition with Flow Enum

@Target(ElementType.ANNOTATION_TYPE)
@interface OAuth2Definition {
    String key();
    String description() default "";
    Flow flow();
    String authorizationUrl() default "";
    String tokenUrl() default "";
    Scope[] scopes() default {};
    
    enum Flow {
        IMPLICIT, ACCESS_CODE, PASSWORD, APPLICATION
    }
}

@Target(ElementType.ANNOTATION_TYPE)
@interface Scope {
    String name();
    String description();
}

ApiModelProperty with AccessMode Enum

// AccessMode is nested within ApiModelProperty
enum AccessMode {
    AUTO, READ_ONLY, READ_WRITE
}

SwaggerDefinition with Scheme Enum

@Target(ElementType.TYPE)
@interface SwaggerDefinition {
    String host() default "";
    String basePath() default "";
    String[] consumes() default {};
    String[] produces() default {};
    Scheme[] schemes() default Scheme.DEFAULT;
    Tag[] tags() default @Tag(name = "");
    SecurityDefinition securityDefinition() default @SecurityDefinition();
    Info info() default @Info(title = "", version = "");
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
    
    enum Scheme {
        DEFAULT, HTTP, HTTPS, WS, WSS
    }
}

Configuration Types

@Target(ElementType.ANNOTATION_TYPE)
@interface Info {
    String title();
    String description() default "";
    String version();
    String termsOfService() default "";
    Contact contact() default @Contact(name = "");
    License license() default @License(name = "");
}

@Target(ElementType.ANNOTATION_TYPE)
@interface Contact {
    String name() default "";
    String url() default "";
    String email() default "";
}

@Target(ElementType.ANNOTATION_TYPE)
@interface License {
    String name() default "";
    String url() default "";
}

Version

Tile

Files

tessl/maven-io-swagger--swagger-annotations

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Swagger Annotations

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Core API Documentation

Parameter Documentation

Data Model Documentation

Response Documentation

Security Configuration

Documentation Metadata

Extension System

Types

ApiKeyAuthDefinition with ApiKeyLocation Enum

OAuth2Definition with Flow Enum

ApiModelProperty with AccessMode Enum

SwaggerDefinition with Scheme Enum

Configuration Types

index.mddocs/