tessl/maven-io-springfox--springfox-swagger2

Swagger 2 API documentation integration library for Spring WebMVC and WebFlux applications

—

Pending

Overview

Eval results

Files

Documentation Generation

Name: tessl/maven-io-springfox--springfox-swagger2
Author: tessl

Core functionality that converts Springfox documentation models into Swagger 2 specification format. Provides comprehensive mapping capabilities for API operations, models, security schemes, and metadata.

Capabilities

ServiceModelToSwagger2Mapper

The main mapper that converts Springfox Documentation objects to Swagger 2 model objects using MapStruct for type-safe mapping.

/**
 * Abstract mapper class that converts Springfox documentation to Swagger 2 format
 * Uses MapStruct for type-safe object mapping
 */
@Mapper(uses = {
    ModelMapper.class,
    ParameterMapper.class,
    SecurityMapper.class,
    LicenseMapper.class,
    VendorExtensionsMapper.class
})
public abstract class ServiceModelToSwagger2Mapper {
    
    /**
     * Maps Springfox Documentation to Swagger 2 Swagger object
     * @param from Springfox Documentation containing API information
     * @return Swagger 2 specification object
     */
    public abstract Swagger mapDocumentation(Documentation from);
    
    /**
     * Maps API info metadata to Swagger 2 Info object
     * @param from Springfox ApiInfo containing metadata
     * @return Swagger 2 Info object
     */
    protected abstract Info mapApiInfo(ApiInfo from);
    
    /**
     * Maps contact information
     * @param from Springfox Contact object
     * @return Swagger 2 Contact object
     */
    protected abstract Contact map(springfox.documentation.service.Contact from);
    
    /**
     * Maps API operations to Swagger 2 Operation objects
     * @param from Springfox Operation containing method details
     * @return Swagger 2 Operation object
     */
    protected abstract Operation mapOperation(springfox.documentation.service.Operation from);
    
    /**
     * Maps API tags for grouping operations
     * @param from Springfox Tag object
     * @return Swagger 2 Tag object
     */
    protected abstract Tag mapTag(springfox.documentation.service.Tag from);
}

Usage Example:

// Typically used internally by the framework
ServiceModelToSwagger2Mapper mapper = // injected by Spring
Documentation documentation = documentationCache.documentationByGroup("default");
Swagger swagger = mapper.mapDocumentation(documentation);

SecurityMapper

Maps security schemes and authorization configurations to Swagger 2 format.

/**
 * Mapper for security schemes and configurations
 */
@Mapper
public class SecurityMapper {
    
    /**
     * Converts resource listing security schemes to Swagger 2 format
     * @param from ResourceListing containing security configuration
     * @return Map of security scheme definitions
     */
    public Map<String, SecuritySchemeDefinition> toSecuritySchemeDefinitions(ResourceListing from);
}

ModelMapper

Maps data model definitions and properties to Swagger 2 format, handling type conversions and property mappings.

/**
 * Mapper for data models and properties
 */
@Mapper
public class ModelMapper {
    
    /**
     * Maps Springfox models to Swagger 2 model definitions
     * Handles type conversions, property mappings, and inheritance
     */
    // Various model mapping methods for different Springfox model types
}

ParameterMapper

Maps API operation parameters to Swagger 2 parameter format.

/**
 * Mapper for operation parameters
 */
@Mapper
public class ParameterMapper {
    
    /**
     * Maps Springfox parameters to Swagger 2 parameter objects
     * Handles query parameters, path parameters, headers, etc.
     */
    // Parameter mapping methods
}

Security Scheme Factories

Factory interfaces and implementations for creating different types of security schemes.

/**
 * Factory interface for creating security scheme definitions
 */
public interface SecuritySchemeFactory {
    /**
     * Creates a security scheme definition from Springfox security scheme
     * @param securityScheme Springfox security scheme
     * @return Swagger 2 security scheme definition
     */
    SecuritySchemeDefinition create(SecurityScheme securityScheme);
}

/**
 * Factory for basic authentication security schemes
 */
public class BasicAuthFactory implements SecuritySchemeFactory {
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
}

/**
 * Factory for OAuth 2 security schemes
 */
public class OAuth2AuthFactory implements SecuritySchemeFactory {
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
}

/**
 * Factory for API key security schemes
 */
public class ApiKeyAuthFactory implements SecuritySchemeFactory {
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
}

Vendor Extensions and Examples

Mappers for handling vendor extensions and example values in API documentation.

/**
 * Mapper for vendor extensions
 */
public class VendorExtensionsMapper {
    /**
     * Maps vendor extension data to Swagger 2 format
     * @param extensions Map of extension data
     * @return Mapped vendor extensions
     */
    public Map<String, Object> mapExtensions(Map<String, Object> extensions);
}

/**
 * Mapper for example values in API documentation
 */
public class ExamplesMapper {
    /**
     * Maps example values to Swagger 2 format
     * @param examples Map of example data
     * @return Mapped examples
     */
    public Map<String, Object> mapExamples(Map<String, Object> examples);
}

Enum and License Mappers

Specialized mappers for enumeration values and license information.

/**
 * Mapper for enumeration types
 */
public class EnumMapper {
    /**
     * Maps enumeration values to Swagger 2 format
     */
    // Enum mapping methods
}

/**
 * Mapper for license information
 */
public class LicenseMapper {
    /**
     * Maps license data to Swagger 2 License objects
     */
    // License mapping methods
}

Mapping Process

The documentation generation follows this process:

Documentation Retrieval: Get Springfox Documentation from DocumentationCache
Model Conversion: Convert Springfox models to Swagger 2 models using specialized mappers
Security Mapping: Transform security schemes using appropriate factories
Parameter Processing: Map operation parameters to Swagger 2 format
Response Mapping: Convert response definitions and examples
Metadata Processing: Map API info, contact, license, and vendor extensions
Path Organization: Organize API operations by paths and HTTP methods

Supported Features

Complete API Mapping: Operations, parameters, responses, and models
Security Integration: Basic Auth, OAuth 2, and API Key authentication
Type Safety: MapStruct-based mapping with compile-time validation
Vendor Extensions: Custom extension support for enhanced documentation
Example Values: Rich example support for parameters and responses
Inheritance Handling: Model inheritance and composition mapping
Enum Support: Enumeration type mapping with allowed values
License and Contact: Complete metadata mapping

Dependencies

The mappers depend on:

MapStruct for annotation-based object mapping
Swagger 2 models (io.swagger.models package)
Springfox service models (springfox.documentation.service package)
Jackson for JSON processing capabilities

Install with Tessl CLI

npx tessl i tessl/maven-io-springfox--springfox-swagger2

docs

configuration.md

documentation-generation.md

index.md

json-serialization.md

web-integration.md

tile.json

tessl/maven-io-springfox--springfox-swagger2