Armeria And OpenApi When Using Armeria-spring-boot3-webflux-starter

May 20, 2025 by ADMIN 68 views

Introduction

When using the armeria-spring-boot3-webflux-starter in a Spring Boot application, it is not uncommon to encounter issues with Swagger and OpenAPI specifications not appearing in the /actuator endpoint. This article aims to provide a detailed explanation of the issue and potential solutions.

The Issue

The problem arises from the way Armeria handles the HTTP server, which is started by Armeria itself, rather than Spring Boot. This means that the GET /actuator request is handled at runtime by ArmeriaSpringActuatorAutoConfiguration.configureExposableWebEndpoint. Unlike Spring Boot's standard configuration, which uses both WebEndpointsSupplier and ControllerEndpointsSupplier to discover endpoints, Armeria only uses WebEndpointsSupplier. As a result, @ControllerEndpoints — such as Swagger and OpenAPI — are not included and do not appear in /actuator.

Thrift Integration and its Impact

The issue is deeply related to Thrift integration through Armeria. The alfa-armeria-thrift-starter hooks into the networking layer via Netty, bypassing Spring Boot Actuator's standard behavior. This integration causes the HTTP server to be started by Armeria, rather than Spring Boot, leading to the exclusion of Swagger and OpenAPI specifications from the /actuator endpoint.

Logs and Debugging

When investigating the cause of the issue, it is essential to examine the logs. The following log snippet indicates that the HTTP server is started by Armeria:

[oss-http-*:8080] com.linecorp.armeria.server.Server : Serving HTTP at /[0:0:0:0:0:0:0:0%0]:8080 - http://127.0.0.1:8080/

Potential Solutions

There are a few potential solutions to this issue:

1. Disable Thrift Integration

One possible solution is to disable Thrift integration by excluding the alfa-armeria-thrift-starter from the project dependencies. This can be achieved by adding the following configuration to the pom.xml file:

<dependency>
    <groupId>com.linecorp.armeria</groupId>
    <artifactId>armeria-spring-boot3-webflux-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.linecorp.armeria</groupId>
            <artifactId>alfa-armeria-thrift-starter</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. Configure Armeria to Use Spring Boot Actuator

Another potential solution is to configure Armeria to use Spring Boot Actuator's standard behavior. This can be achieved by adding the following configuration to the application.properties file:

spring.armeria.actuator.enabled=true

3. Implement a Custom WebEndpointsSupplier

A more complex solution involves implementing a custom WebEndpointsSupplier to include Swagger and OpenAPI specifications in the /actuator endpoint. This requires creating a custom class that implements the WebEndpointsSupplier interface and it with the Spring Boot application.

Conclusion

In conclusion, the issue of Swagger and OpenAPI specifications not appearing in the /actuator endpoint when using the armeria-spring-boot3-webflux-starter is a complex problem that requires a deep understanding of Armeria and Spring Boot Actuator. By disabling Thrift integration, configuring Armeria to use Spring Boot Actuator, or implementing a custom WebEndpointsSupplier, developers can resolve this issue and ensure that their Swagger and OpenAPI specifications are properly included in the /actuator endpoint.

References

Armeria GitHub Discussion
Spring Boot Actuator Documentation
Armeria Documentation
Armeria and OpenApi when using armeria-spring-boot3-webflux-starter: Q&A ====================================================================

Introduction

In our previous article, we discussed the issue of Swagger and OpenAPI specifications not appearing in the /actuator endpoint when using the armeria-spring-boot3-webflux-starter. We also explored potential solutions to this issue. In this article, we will provide a Q&A section to address some of the most frequently asked questions related to this topic.

Q: What is the root cause of the issue?

A: The root cause of the issue is the way Armeria handles the HTTP server, which is started by Armeria itself, rather than Spring Boot. This means that the GET /actuator request is handled at runtime by ArmeriaSpringActuatorAutoConfiguration.configureExposableWebEndpoint. Unlike Spring Boot's standard configuration, which uses both WebEndpointsSupplier and ControllerEndpointsSupplier to discover endpoints, Armeria only uses WebEndpointsSupplier. As a result, @ControllerEndpoints — such as Swagger and OpenAPI — are not included and do not appear in /actuator.

Q: How can I disable Thrift integration?

A: To disable Thrift integration, you can exclude the alfa-armeria-thrift-starter from the project dependencies. This can be achieved by adding the following configuration to the pom.xml file:

<dependency>
    <groupId>com.linecorp.armeria</groupId>
    <artifactId>armeria-spring-boot3-webflux-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.linecorp.armeria</groupId>
            <artifactId>alfa-armeria-thrift-starter</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Q: How can I configure Armeria to use Spring Boot Actuator?

A: To configure Armeria to use Spring Boot Actuator's standard behavior, you can add the following configuration to the application.properties file:

spring.armeria.actuator.enabled=true

Q: How can I implement a custom WebEndpointsSupplier?

A: To implement a custom WebEndpointsSupplier, you need to create a custom class that implements the WebEndpointsSupplier interface and register it with the Spring Boot application. Here is an example of how you can implement a custom WebEndpointsSupplier:

@Component
public class CustomWebEndpointsSupplier implements WebEndpointsSupplier {

    @Override
    public List<WebEndpoint> getWebEndpoints() {
        List<WebEndpoint> webEndpoints = new ArrayList<>();
        webEndpoints.add(new WebEndpoint("/swagger-ui", "Swagger UI"));
        webEndpoints.add(new WebEndpoint("/v3/api-docs", "OpenAPI"));
        return webEndpoints;
    }
}

Q: What are the benefits of using Armeria with Spring Boot?

A: Armeria is a high-performance, non-blocking web framework that can be used with Spring Boot to build scalable and efficient web applications. Some of the benefits of using Armeria with Spring Boot include:

High-performance and low-latency

Non-blocking I/O and asynchronous programming
Support for HTTP/2 and WebSockets
Easy integration with Spring Boot and other Java frameworks

Q: What are the limitations of using Armeria with Spring Boot?

A: While Armeria is a powerful and flexible web framework, it also has some limitations when used with Spring Boot. Some of the limitations include:

Steeper learning curve due to its non-blocking and asynchronous programming model
Limited support for certain features and protocols, such as HTTP/1.1 and TCP
Potential conflicts with other Java frameworks and libraries