In this post, we'll explore how to configure OpenAPI in your Spring Boot application and add a convenient redirection from the root URL to the Swagger UI. This setup will improve your API documentation and make it more accessible to developers.

OpenAPI Bean Configuration

First, let's create a configuration class to customize our OpenAPI documentation:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.info.GitProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI(GitProperties gitProperties) {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Catalog API")
                        .description("REST API for managing a book catalog. Application version: "+ gitProperties.get("build.version"))
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("Book Catalog Team")
                                .email("support@bookcatalog.com")
                                .url("https://github.com/vlaship/book-catalog"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                );
    }
}

This configuration creates a custom OpenAPI bean with basic information about your API. You can further customize this by adding more details, such as contact information, license, or external documentation.
We can use GitProperties to provide more details.

Root URL Redirection Controller

Next, let's create a controller to redirect users from the root URL to the Swagger UI:

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class OpenApiController {
    @GetMapping("/")
    public String index() {
        return "redirect:swagger-ui.html";
    }
}

This simple controller uses a @GetMapping for the root URL ("/") and redirects to the Swagger UI HTML page.

Updating application.yaml

This configuration file, often named application.yml, plays a crucial role in defining various aspects of your application's behavior.

spring:
  application:
    name: book-catalog
    version: '@project.version@'
  mvc:
    problemdetails:
      enabled: true

management:
  endpoints:
    web:
      exposure:
        include: '*'
  info:
    git:
      mode: full

server:
  port: 8888
  servlet:
    context-path: /${spring.application.name}
  error:
    whitelabel:
      enabled: false

The provided YAML configuration covers several key areas of your Spring Boot application:

1. Application Properties:

name: Defines the application's name, here set to book-catalog.

version: References a placeholder, likely populated during the build process, to specify the application's version.

1. MVC Configuration:

problemdetails.enabled: Enables detailed problem reports in the response body for exceptions.

1. Management Endpoints:

endpoints.web.exposure.include: '*':** Exposes all actuator endpoints for monitoring and management purposes.

info.git.mode: full: Provides detailed Git information in the /info endpoint.

1. Server Configuration:

port: Sets the port on which the server listens for incoming requests (default 8080, here set to 8888).

servlet.context-path: Defines the context path for the application, ensuring requests are routed correctly.

error.whitelabel.enabled: false: Disables the default whitelabel error page, allowing for more informative error messages during development.

Adding banner.txt

1. Create banner.txt file

Create a new file named banner.txt within the src/main/resources directory of your Spring Boot project.

2. Add service details to banner.txt

You can add any text or ASCII art to this file. Here's an example:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.info.GitProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI(GitProperties gitProperties) {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Catalog API")
                        .description("REST API for managing a book catalog. Application version: "+ gitProperties.get("build.version"))
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("Book Catalog Team")
                                .email("support@bookcatalog.com")
                                .url("https://github.com/vlaship/book-catalog"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                );
    }
}

This approach adds a professional touch to your application startup and provides valuable information at a glance.

Adding Dockerfile

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class OpenApiController {
    @GetMapping("/")
    public String index() {
        return "redirect:swagger-ui.html";
    }
}

Layer Extraction: Creating separate layers for dependencies, improving build efficiency and reducing image size updates.
Multi-stage Build: Utilizing a multi-stage build process to separate the build environment from the runtime environment, resulting in a smaller and more efficient final image.
Lightweight Base Image: Using a minimal base image like azul/zulu-openjdk-alpine:21-jre-headless to further reduce the image size.

This approach leads to faster builds, smaller image sizes, and improved overall performance for your Spring Boot application within a Docker container.

The above is the detailed content of SpringBoot Web Service - Part Initial Configuration. For more information, please follow other related articles on the PHP Chinese website!