Web Controllers

/**
 * REST controller providing JSON configuration for Swagger UI
 * Serves configuration data needed by the Swagger UI JavaScript application
 */
@RestController
public class SwaggerConfigResource {
    
    /**
     * Constructor requiring common welcome functionality
     * @param swaggerWelcomeCommon Common functionality for URL building and configuration
     */
    public SwaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);

    /**
     * Returns OpenAPI configuration as JSON for Swagger UI initialization
     * Provides URLs, paths, and settings required by the Swagger UI frontend
     * @param request HTTP request for context path and URL building
     * @return Map containing configuration parameters for Swagger UI
     */
    @Operation(hidden = true)
    @GetMapping(value = "/v3/api-docs/swagger-config", produces = MediaType.APPLICATION_JSON_VALUE)
    public Map<String, Object> openapiJson(HttpServletRequest request);
}

// Configuration is automatically served at /v3/api-docs/swagger-config
// JavaScript in Swagger UI fetches this to initialize the interface

/**
 * Controller handling Swagger UI welcome page and redirects for WebMVC applications
 * Extends SwaggerWelcomeCommon for shared URL building and configuration logic
 */
@Controller
public class SwaggerWelcomeWebMvc extends SwaggerWelcomeCommon {
    
    /**
     * Constructor for WebMVC-specific welcome controller
     * @param swaggerUiConfig Swagger UI configuration properties
     * @param springDocConfigProperties SpringDoc configuration properties
     * @param springWebProvider Spring web provider for WebMVC-specific functionality
     */
    public SwaggerWelcomeWebMvc(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);

    /**
     * Handles requests to Swagger UI path and redirects to actual UI location
     * Builds proper redirect URL considering context paths and servlet paths
     * @param request HTTP request for context and path information
     * @return ResponseEntity with redirect status and location header
     */
    @Operation(hidden = true)
    @GetMapping("${springdoc.swagger-ui.path:/swagger-ui.html}")
    public ResponseEntity<Void> redirectToUi(HttpServletRequest request);

    /**
     * Calculates UI root path for WebMVC applications
     * Considers servlet context path and MVC servlet path
     * @param swaggerUiConfigParameters Configuration parameters to update
     * @param sbUrls Additional URL builders for path calculation
     */
    protected void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        StringBuilder... sbUrls);

    /**
     * Builds URLs with context path for WebMVC applications
     * @param contextPath Application context path
     * @param docsUrl Documentation URL to build
     * @return Complete URL with proper context path
     */
    protected String buildUrl(String contextPath, String docsUrl);

    /**
     * Builds API documentation URL for WebMVC applications
     * @param swaggerUiConfigParameters Configuration parameters to update with API docs URL
     */
    protected void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);

    /**
     * Builds URL with full context path including path prefix
     * @param swaggerUiConfigParameters Configuration parameters
     * @param swaggerUiUrl Swagger UI URL to build
     * @return Complete URL with context path and prefix
     */
    protected String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        String swaggerUiUrl);

    /**
     * Builds Swagger configuration URL for WebMVC applications
     * @param swaggerUiConfigParameters Configuration parameters to update with config URL
     */
    protected void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
}

/**
 * Actuator controller endpoint for Swagger UI on management port
 * Provides Swagger UI functionality through Spring Boot Actuator infrastructure
 */
@ControllerEndpoint(id = "swaggerui")
public class SwaggerWelcomeActuator extends SwaggerWelcomeCommon {
    
    /**
     * Constructor for actuator-based welcome controller
     * @param swaggerUiConfig Swagger UI configuration properties
     * @param springDocConfigProperties SpringDoc configuration properties
     * @param webEndpointProperties Actuator web endpoint properties for path building
     */
    public SwaggerWelcomeActuator(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties, WebEndpointProperties webEndpointProperties);

    /**
     * Redirects to Swagger UI from actuator endpoint
     * Handles redirect from management port to Swagger UI interface
     * @param request HTTP request for context and path building
     * @return ResponseEntity with redirect to Swagger UI
     */
    @Operation(hidden = true)
    @GetMapping("/")
    public ResponseEntity<Void> redirectToUi(HttpServletRequest request);

    /**
     * Returns OpenAPI configuration from actuator endpoint
     * Serves Swagger UI configuration through management port
     * @param request HTTP request for context building
     * @return Map containing Swagger UI configuration parameters
     */
    @Operation(hidden = true)
    @GetMapping(value = "/swagger-config", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public Map<String, Object> openapiJson(HttpServletRequest request);

    /**
     * Calculates UI root path for actuator deployment
     * Uses actuator base path for proper URL building
     * @param swaggerUiConfigParameters Configuration parameters to update
     * @param sbUrls Additional URL builders
     */
    protected void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        StringBuilder... sbUrls);

    /**
     * Builds API documentation URL for actuator deployment
     * @param swaggerUiConfigParameters Configuration parameters to update
     */
    protected void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);

    /**
     * Builds URL with context path for actuator deployment
     * @param swaggerUiConfigParameters Configuration parameters
     * @param swaggerUiUrl URL to build
     * @return Complete URL with actuator context path
     */
    protected String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        String swaggerUiUrl);

    /**
     * Builds Swagger configuration URL for actuator deployment
     * @param swaggerUiConfigParameters Configuration parameters to update
     */
    protected void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
}

/**
 * Controller providing root path redirect to Swagger UI
 * Enables accessing Swagger UI from application root when configured
 */
@Controller
public class SwaggerUiHome {
    
    /**
     * Swagger UI path configuration property
     */
    @Value("${springdoc.swagger-ui.path:/swagger-ui.html}")
    private String swaggerUiPath;

    /**
     * MVC servlet path configuration property  
     */
    @Value("${spring.mvc.servlet.path:}")
    private String mvcServletPath;

    /**
     * Redirects root path requests to Swagger UI
     * Builds redirect URL considering servlet path and Swagger UI path
     * @return Redirect view to Swagger UI main page
     */
    @GetMapping("/")
    @Operation(hidden = true)
    public String index();
}

/**
 * Abstract base class for Swagger UI welcome controllers
 * Provides common URL building and configuration functionality
 */
public abstract class SwaggerWelcomeCommon extends AbstractSwaggerWelcome {
    
    /**
     * Constructor for common welcome functionality
     * @param swaggerUiConfig Swagger UI configuration properties
     * @param springDocConfigProperties SpringDoc configuration properties
     */
    protected SwaggerWelcomeCommon(SwaggerUiConfigProperties swaggerUiConfig, 
        SpringDocConfigProperties springDocConfigProperties);

    /**
     * Handles redirect to Swagger UI with query parameter forwarding
     * Builds redirect response with proper status and location header
     * @param request HTTP request for context and query parameters
     * @return ResponseEntity with redirect to Swagger UI
     */
    protected ResponseEntity<Void> redirectToUi(HttpServletRequest request);

    /**
     * Returns OpenAPI configuration parameters as JSON
     * Builds configuration map with URLs and settings for Swagger UI
     * @param request HTTP request for context building
     * @return Map containing configuration parameters
     */
    protected Map<String, Object> openapiJson(HttpServletRequest request);

    /**
     * Calculates OAuth2 redirect URL for authentication
     * Builds OAuth2 redirect URL if not explicitly configured
     * @param swaggerUiConfigParameters Configuration parameters to update
     * @param uriComponentsBuilder URI builder for URL construction
     */
    protected void calculateOauth2RedirectUrl(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        UriComponentsBuilder uriComponentsBuilder);

    /**
     * Builds configuration from current request context path
     * Updates configuration parameters based on request context
     * @param swaggerUiConfigParameters Configuration parameters to update
     * @param request HTTP request for context information
     */
    void buildFromCurrentContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        HttpServletRequest request);

    // Abstract methods implemented by subclasses:
    protected abstract void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        StringBuilder... sbUrls);
    protected abstract void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
    protected abstract String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
        String swaggerUiUrl);
    protected abstract void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
}

GET ${springdoc.swagger-ui.path:/swagger-ui.html} → SwaggerWelcomeWebMvc.redirectToUi()
GET /v3/api-docs/swagger-config → SwaggerConfigResource.openapiJson()
GET / (optional)              → SwaggerUiHome.index()

GET /actuator/swaggerui/      → SwaggerWelcomeActuator.redirectToUi()
GET /actuator/swaggerui/swagger-config → SwaggerWelcomeActuator.openapiJson()

// After application startup, these endpoints are automatically available:
// http://localhost:8080/swagger-ui.html (redirects to actual UI)
// http://localhost:8080/v3/api-docs/swagger-config (JSON configuration)

@Controller
public class CustomSwaggerWelcome {
    
    @GetMapping("/api-docs")
    public String customRedirect() {
        return "redirect:/swagger-ui.html";
    }
}

management:
  server:
    port: 8081
springdoc:
  use-management-port: true

// Swagger UI available at:
// http://localhost:8081/actuator/swaggerui/

server:
  servlet:
    context-path: /myapp
spring:
  mvc:
    servlet:
      path: /api

// Swagger UI automatically available at:
// http://localhost:8080/myapp/api/swagger-ui.html