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

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

—

Pending

Overview

Eval results

Files

Web Integration

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

REST endpoints and controllers that serve generated Swagger 2 JSON documentation to clients and Swagger UI applications. Provides both WebMVC and WebFlux controller implementations for different Spring application types.

Capabilities

Swagger2ControllerWebMvc

Spring WebMVC controller that serves Swagger 2 JSON documentation via HTTP endpoints in servlet-based applications.

/**
 * Controller for serving Swagger 2 documentation in WebMVC applications
 * Handles HTTP requests and returns JSON-formatted Swagger specifications
 */
@Controller
@ConditionalOnClass(name = "javax.servlet.http.HttpServletRequest")
@ApiIgnore
public class Swagger2ControllerWebMvc {
    
    /**
     * Constructor for WebMVC Swagger controller
     * @param environment Spring environment for property resolution
     * @param documentationCache Cache for accessing documentation by group
     * @param mapper Mapper for converting documentation to Swagger format
     * @param jsonSerializer Serializer for converting Swagger objects to JSON
     */
    public Swagger2ControllerWebMvc(
        Environment environment,
        DocumentationCache documentationCache,
        ServiceModelToSwagger2Mapper mapper,
        JsonSerializer jsonSerializer
    );
    
    /**
     * GET endpoint that returns Swagger 2 JSON documentation
     * Default endpoint: /v2/api-docs
     * Configurable via: springfox.documentation.swagger.v2.path
     * 
     * @param swaggerGroup Optional group name for multi-group documentation (default: "default")
     * @param servletRequest HTTP servlet request for host/path resolution
     * @return ResponseEntity containing JSON-formatted Swagger specification
     */
    @RequestMapping(
        value = "/v2/api-docs",
        method = RequestMethod.GET,
        produces = { "application/json", "application/hal+json" }
    )
    @PropertySourcedMapping(
        value = "${springfox.documentation.swagger.v2.path}",
        propertyKey = "springfox.documentation.swagger.v2.path"
    )
    @ResponseBody
    public ResponseEntity<Json> getDocumentation(
        @RequestParam(value = "group", required = false) String swaggerGroup,
        HttpServletRequest servletRequest
    );
}

Usage Example:

# Get default group documentation
curl http://localhost:8080/v2/api-docs

# Get specific group documentation
curl http://localhost:8080/v2/api-docs?group=admin-api

# Custom endpoint path (if configured)
curl http://localhost:8080/api/swagger.json

Swagger2ControllerWebFlux

Spring WebFlux controller that serves Swagger 2 JSON documentation via HTTP endpoints in reactive applications.

/**
 * Controller for serving Swagger 2 documentation in WebFlux applications
 * Handles reactive HTTP requests and returns JSON-formatted Swagger specifications
 */
@Controller
@ConditionalOnClass(name = "org.springframework.web.reactive.BindingContext")
@ApiIgnore
public class Swagger2ControllerWebFlux {
    
    /**
     * Constructor for WebFlux Swagger controller
     * @param documentationCache Cache for accessing documentation by group
     * @param mapper Mapper for converting documentation to Swagger format
     * @param jsonSerializer Serializer for converting Swagger objects to JSON
     */
    public Swagger2ControllerWebFlux(
        DocumentationCache documentationCache,
        ServiceModelToSwagger2Mapper mapper,
        JsonSerializer jsonSerializer
    );
    
    /**
     * GET endpoint that returns Swagger 2 JSON documentation
     * Default endpoint: /v2/api-docs
     * Configurable via: springfox.documentation.swagger.v2.path
     * 
     * @param swaggerGroup Optional group name for multi-group documentation (default: "default")
     * @param request Reactive HTTP request for host/path resolution
     * @return ResponseEntity containing JSON-formatted Swagger specification
     */
    @RequestMapping(
        value = "/v2/api-docs",
        method = RequestMethod.GET,
        produces = { "application/json", "application/hal+json" }
    )
    @PropertySourcedMapping(
        value = "${springfox.documentation.swagger.v2.path}",
        propertyKey = "springfox.documentation.swagger.v2.path"
    )
    @ResponseBody
    public ResponseEntity<Json> getDocumentation(
        @RequestParam(value = "group", required = false) String swaggerGroup,
        ServerHttpRequest request
    );
}

Usage Example:

# Get default group documentation (same as WebMVC)
curl http://localhost:8080/v2/api-docs

# Get specific group documentation
curl http://localhost:8080/v2/api-docs?group=admin-api

Endpoint Configuration

Default Endpoint

Both controllers serve documentation at /v2/api-docs by default, which is the standard Swagger 2 documentation endpoint expected by Swagger UI and other tools.

Custom Endpoint Path

You can customize the endpoint path using the springfox.documentation.swagger.v2.path property:

# application.properties
springfox.documentation.swagger.v2.path=/api/swagger.json

Host Override

WebMVC controller supports hostname override via the springfox.documentation.swagger.v2.host property:

# application.properties
springfox.documentation.swagger.v2.host=api.example.com

Content Types

Both controllers support multiple content types:

application/json - Standard JSON format
application/hal+json - HAL (Hypertext Application Language) JSON format

Group-based Documentation

Both controllers support documentation groups, allowing you to serve different API documentation for different parts of your application:

// Multiple Docket beans create different groups
@Bean
public Docket publicApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("public")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.public"))
        .build();
}

@Bean
public Docket adminApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("admin")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.admin"))
        .build();
}

Access different groups:

/v2/api-docs - Default group
/v2/api-docs?group=public - Public API group
/v2/api-docs?group=admin - Admin API group

Request Handling

WebMVC Implementation

Uses HttpServletRequest for accessing request information
Resolves hostname and port from servlet request
Supports servlet-specific features and filters
Compatible with Spring Security servlet configurations

WebFlux Implementation

Uses ServerHttpRequest for accessing request information
Reactive, non-blocking request handling
Resolves hostname from reactive request URI
Compatible with Spring Security WebFlux configurations

Response Format

Both controllers return ResponseEntity<Json> where:

Success (200): Returns JSON-formatted Swagger 2 specification
Not Found (404): When specified documentation group doesn't exist

Example success response structure:

{
  "swagger": "2.0",
  "info": {
    "title": "API Documentation",
    "version": "1.0.0"
  },
  "host": "localhost:8080",
  "basePath": "/",
  "paths": {
    "/api/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "Successful operation"
          }
        }
      }
    }
  }
}

Integration with Swagger UI

These endpoints are designed to work seamlessly with Swagger UI:

// Swagger UI configuration
SwaggerUIBundle({
  url: 'http://localhost:8080/v2/api-docs',
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ]
});

Error Handling

Both controllers handle common error scenarios:

Missing Documentation Group: Returns 404 with appropriate logging
Invalid Group Parameter: Falls back to default group
Serialization Errors: Handled by framework error handling

Conditional Loading

Controllers are conditionally loaded based on classpath:

WebMVC Controller: Only when servlet API is present
WebFlux Controller: Only when reactive web stack is present

This ensures the appropriate controller is used based on your application type.

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