Forem: Michèle

Documents Spring Boot actuator endpoint with OpenApi

Michèle — Wed, 06 Jan 2021 00:20:41 +0000

In my previous post, I shown how to create a custom Spring Boot actuator endpoint. It could be useful to have pretty web interface to document these endpoints and allow other people to easily access your api in a pretty way. You know, I'm a girl, I like pretty things ;)

So, I chosen to use OpenApi which is usually easy to use, usually... In fact, by default, actuator endpoint are not shown with OpenApi, and it was hard to find how to do. That's why I decide to write this small post.

First of all, you'll need this dependencies :

    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.0'
    implementation group: 'org.springdoc', name: 'springdoc-openapi-data-rest', version: '1.5.0'

Then, you just need to add these properties...

springdoc:
  show-actuator: true

... And you got your actuator endpoint documentation !

... And you can test your endpoints

How to unit test a custom actuator endpoint

Michèle — Mon, 04 Jan 2021 03:57:21 +0000

Previously, I posted on "How to create a custom endpoint to monitor Jira", this is the second part, showing how to unit test this endpoint with SpringBoot MockMvc, Mokito and PowerMokito.

Here the list of dependencies required :

    implementation 'junit:junit:4.12'
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
        exclude group: "com.vaadin.external.google", module:"android-json"
    }
    testImplementation group: 'com.konghq', name: 'unirest-mocks', version: '3.11.06'
    testImplementation group: 'org.powermock', name: 'powermock-module-junit4', version: '2.0.9'
    testImplementation group: 'org.powermock', name: 'powermock-api-mockito2', version: '2.0.9'

We first need a class that load our configuration class used by the JiraConnectorService.

@TestConfiguration
public class TestConfig {

    @Bean
    public JiraConfig getJiraConfig(){
        return new JiraConfig();
    }
}

Test the service to be sure it returns the good data according to the Jira endpoint response.
To do so, we need to mock the Unirest.get() call and response.

@RunWith(PowerMockRunner.class)
@PowerMockRunnerDelegate(SpringRunner.class)
@PrepareForTest(Unirest.class)
@Import({TestConfig.class})
@PowerMockIgnore({"javax.*.*", "com.sun.*", "org.xml.*"})
@SpringBootTest
public class JiraConnectorServiceTest {

    @Mock
    private GetRequest getRequest;
    @Autowired
    JiraConnectorService jiraConnectorService;
    @Autowired
    JiraConfig jiraConfig;

    @Test
    public void getResponseTimeTest() throws Exception {

        JsonNode json = new JsonNode("{\"result\":10}");

        HttpResponse<JsonNode> mockResponse = mock(HttpResponse.class);
        when(mockResponse.getStatus()).thenReturn(200);
        when(mockResponse.getBody()).thenReturn(json);

        String mySelfEndPointUrl = jiraConfig.getHost() + jiraConfig.getApiPath() + JiraConnectorService.JIRA_MYSELF_ENDPOINT;

        PowerMockito.mockStatic(Unirest.class);
        when(Unirest.get(mySelfEndPointUrl)).thenReturn(getRequest);
        when(getRequest.header(JiraConnectorService.HEADER_ACCEPT, JiraConnectorService.HEADER_APP_JSON)).thenReturn(getRequest);
        when(getRequest.basicAuth(jiraConfig.getUser(), jiraConfig.getPassword())).thenReturn(getRequest);
        when(getRequest.asJson()).thenReturn(mockResponse);

        ResponseTimeData data = jiraConnectorService.getResponseTime();
        Assert.assertEquals(HttpStatus.OK.value(), data.getHttpStatusCode());
        Assert.assertTrue(data.getTime() > 0);

    }

We have to use PowerMockito and @RunWith(PowerMockRunner.class) annotation to mock the static method Unirest.get(..).

We can only use one @RunWith annotation, that's why we add @PowerMockRunnerDelegate(SpringRunner.class) to load the Spring context.

Then test the endpoint :


@RunWith(SpringRunner.class)
@Import({TestConfig.class})
@AutoConfigureMockMvc
@SpringBootTest
public class RestJiraEndPointTest {

    private static final String ACTUATOR_URI = "/management";

    @MockBean
    private JiraConnectorService jiraConnectorService;
    @Autowired
    private MockMvc mockMvc;

    @Test
    public void healthDtl_DOWN() throws Exception {

        ResponseTimeData data = new ResponseTimeData();
        data.setTime(-1);
        data.setHttpStatusCode(HttpStatus.SERVICE_UNAVAILABLE.value());
        data.setMessage("Service unavailable");

        Mockito.when(jiraConnectorService.getResponseTime()).thenReturn(data);

        RequestBuilder requestBuilder = MockMvcRequestBuilders.get(ACTUATOR_URI + "/jira/healthDtl")
                .accept(MediaType.APPLICATION_JSON);

        this.mockMvc.perform(requestBuilder)
                .andDo(MockMvcResultHandlers.print())
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.jsonPath("$.status").value("DOWN"));
    }

    @Test
    public void healthDtl_UP() throws Exception {

        ResponseTimeData data = new ResponseTimeData();
        data.setTime(235L);
        data.setHttpStatusCode(HttpStatus.OK.value());
        data.setMessage("Ok");

        Mockito.when(jiraConnectorService.getResponseTime()).thenReturn(data);

        RequestBuilder requestBuilder = MockMvcRequestBuilders.get(ACTUATOR_URI + "/jira/healthDtl")
                .accept(MediaType.APPLICATION_JSON);

        this.mockMvc.perform(requestBuilder)
                .andDo(MockMvcResultHandlers.print())
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.jsonPath("$.status").value("UP"))
                .andExpect(MockMvcResultMatchers.jsonPath("$.responseTimeMs").value("235"));
    }
}

I first tried to use @WebMvcTest(RestJiraEndPoint.class) instead of @SpringBootTest but without success. Spring seems to not recognized @RestControllerEndpoint as a rest controller. So, you have to use @SpringBootTest and @AutoConfigureMockMvc.

How to create a custom actuator endpoint to monitor Jira

Michèle — Mon, 04 Jan 2021 00:50:00 +0000

Spring Boot Actuator offers you a set of endpoints to monitor your application, but sometimes you may need to create a custom endpoint to get specific metrics.

There are 2 way to do custom endpoint:

custom endpoint with @Endpoint,
controller endpoint with @RestControllerEndpoint, we will see only the second one.

In our example we don't create a custom endpoint for our application but to monitor our Jira server hosted externally. Indeed we need to know if it is up or down and how many time it spend to return a response.

You will need the following dependecies :

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation "org.springframework.boot:spring-boot-starter-web"
    implementation "org.springframework.boot:spring-boot-starter-security"
    implementation 'org.springframework.boot:spring-boot-starter-tomcat'
    implementation group: 'com.konghq', name: 'unirest-java', version: '3.11.06'
    implementation group: 'com.fasterxml.jackson.core', name: 'jackson-annotations', version: '2.11.3'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.0'
    implementation group: 'org.springdoc', name: 'springdoc-openapi-data-rest', version: '1.5.0'
    }

Here, our application.yml file with actuator and jira server connection properties

management:
  endpoints:
    web:
      exposure:
          include: '*'
      base-path: "/management"
  security:
    enabled: false

  endpoint:
    health:
      show-details: always

app:
  config:
    jira:
      host: "https://myjiraserver"
      user: "jiraUser"
      password: "jirapwd"
      api-path: "/rest/api/2"

We mapped the jira properties with a java configuration class.

@Component
@ConfigurationProperties("app.config.jira")
@Validated
public class JiraConfig {

    @NotEmpty
    protected String host;
    @NotEmpty
    protected String user;
    @NotEmpty
    protected String password;
    @NotEmpty
    protected String apiPath;


    public String getHost() {
        return host;
    }

    public void setHost(String host) {
        this.host = host;
    }

    public String getUser() {
        return user;
    }

    public void setUser(String user) {
        this.user = user;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getApiPath() {
        return apiPath;
    }

    public void setApiPath(String apiPath) {
        this.apiPath = apiPath;
    }
}

Then, here is the service that call jira endpoint and give the response time.

@Service
public class JiraConnectorService {

    private static final Logger logger = LoggerFactory.getLogger(JiraConnectorService.class);
    public static final String HEADER_ACCEPT = "accept";
    public static final String HEADER_APP_JSON = "application/json";
    public static final String JIRA_MYSELF_ENDPOINT = "/myself";

    private JiraConfig jiraConfig;

    @Autowired
    public void setJiraConfig(JiraConfig jiraConfig) {
        this.jiraConfig = jiraConfig;
    }

    public ResponseTimeData getResponseTime() throws UnirestException {
        logger.info("Get responseTime info");
        String mySelfEndPointUrl = jiraConfig.getHost() + jiraConfig.getApiPath() + JIRA_MYSELF_ENDPOINT;

        logger.info("Call {}", mySelfEndPointUrl);
        ResponseTimeData data = new ResponseTimeData();
        long start = System.currentTimeMillis();

        HttpResponse<JsonNode> jsonResponse = Unirest.get(mySelfEndPointUrl)
                .basicAuth(jiraConfig.getUser(), jiraConfig.getPassword())
                .header(HEADER_ACCEPT, HEADER_APP_JSON)
                .asJson();

        data.setTime(System.currentTimeMillis() - start);
        data.setHttpStatusCode(jsonResponse.getStatus());
        data.setMessage(jsonResponse.getStatusText());

        logger.info("Call {} successfull", mySelfEndPointUrl);
        return data;
    }
}

Data model

public class ResponseTimeData {

    private long time;
    private int httpStatusCode;
    private String message;


    public long getTime() {
        return time;
    }

    public void setTime(long time) {
        this.time = time;
    }

    public int getHttpStatusCode() {
        return httpStatusCode;
    }

    public void setHttpStatusCode(int httpStatusCode) {
        this.httpStatusCode = httpStatusCode;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

public class HealthDtl {

    protected String status;
    private int httpStatusCode;
    private String message;
    private Long responseTimeMs;

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public int getHttpStatusCode() {
        return httpStatusCode;
    }

    public void setHttpStatusCode(int httpStatusCode) {
        this.httpStatusCode = httpStatusCode;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public Long getResponseTimeMs() {
        return responseTimeMs;
    }

    public void setResponseTimeMs(Long responseTimeMs) {
        this.responseTimeMs = responseTimeMs;
    }
}

And now, the custom rest endpoint !

@Component
@RestControllerEndpoint(id = "jira")
public class RestJiraEndPoint {

    private static final Logger logger = LoggerFactory.getLogger(RestJiraEndPoint.class);

    private final JiraConnectorService jiraConnectorService;

    public RestJiraEndPoint(JiraConnectorService jiraConnectorService, MessageSource messageSource){
        this.jiraConnectorService = jiraConnectorService;
    }


    @GetMapping("/healthDtl")
    @ResponseBody
    public ResponseEntity<HealthDtl> healthDtl() {
        logger.info("/jira/healthDtl endpoint called");

        HealthDtl health = new HealthDtl();
        ResponseTimeData data = new ResponseTimeData();
        try {
            data = jiraConnectorService.getResponseTime();
            if(data.getHttpStatusCode() == HttpStatus.OK.value())
                health.setStatus("UP");
            else
                health.setStatus("DOWN");
            health.setMessage(data.getMessage());
            health.setResponseTimeMs(data.getTime());
        } catch (UnirestException e) {
            logger.error(e.getLocalizedMessage(), e);
            health.setStatus("DOWN");
            health.setMessage(e.getMessage());
        }
        health.setHttpStatusCode(data.getHttpStatusCode());

        return new ResponseEntity<>(health, HttpStatus.OK);
    }
}

You have now a new actuator endpoint /management/jira/healthDtl that replies :

{
"status":"UP",
"httpStatusCode":200,
"message":"",
"responseTimeMs":369
}

I'll add a new post on how to unit test this custom actuator endpoint.