Recently, the front-end team I’m on really saw how the back-end team was swamped. During the sprint retro, we expressed that we wanted to help out any way we could. So, with their help, we got set up in IntelliJ and back-end’s Spring Boot application. My team ended up getting wrapped up in our main projects. I put aside some time on my own to look at back-end’s backlog. After touching base with them and seeing where I could best help them, I picked up a technical debt ticket around automating the validation of the OpenAPI spec.
It was really a great adventure and learning opportunity! I had never worked before with Gradle and Spring Boot in any professional capacity, but I know my way around Gradle now. 😀
The requirements were:
- the validation would be automated
- it could be integrated into the CI/CD flow with GitHub actions
At first, I fell down a deep rabbit hole with trying to implement a custom Gradle Task with plain Java files. The Gradle 8.4 documentation actually pointed people to write them in Groovy or Kotlin, but I think I must have hit a random blog through a Google search, and gotten stuck there. I’m sure it could have worked, but I had already surpassed my initial timebox.
Then, I tried to solve it the simplest way, by using the springdoc-OpenAI Gradle plugin. But that required to run the application, and we wanted to avoid that in the CI/CD flow.
Finally, I went back to the original concept of custom Gradle Tasks, but kept it simple with plain Groovy. Then, I found the winning combination. A blog suggested validating the OpenAPI spec in test cases. The final solution was as follows:
- Writing custom Gradle Tasks in plain Groovy that executed test cases
- This case would manually generate the OpenAPI spec from the code
- Then executing a local shell script that loads a npm library to manually validate the generated spec.
It’s lightweight, it can run easily in a CI/CD flow, and implementing it with straight Groovy keeps the `build.gradle` file light.
I added the custom task to the gradlew command in the appropriate GitHub Action workflow file.
I added the variables extraction.api-spec.json and springdoc.api-docs.path to the application.properties file.
build.gradle
tasks.register("validateOpenApiDocs", Exec) {
group = "documentation"
description = "Validates locally generated OpenApi spec"
def stdout = new ByteArrayOutputStream()
ignoreExitValue true
doFirst() {
println "Validating generated Open API docs..."
}
commandLine './validate-docs.sh'
doLast() {
ObjectMapper mapper = new ObjectMapper();
JsonNode taskResult = mapper.readTree(stdout.toString())
if (taskResult.valid.equals(false)) {
println "FAILED"
println taskResult.errors
} else {
println "OpenAPI spec validation passed!"
}
}
}validate-docs.sh
#!/bin/bash
npx -p @seriousme/openapi-schema-validator validate-api docs.jsonApiSpecJsonFileExtractor.java
@SpringBootTest
@ActiveProfiles("test")
public class ApiSpecJsonFileExtractor {
@Value("${extraction.api-spec.json}")
String filename;
@Value("${springdoc.api-docs.path}")
String apiDocJsonPath;
<snip>
MockMvc mvc;
@BeforeEach
public void setup() {
mvc = MockMvcBuilders.webAppContextSetup(context).apply(springSecurity()).build();
}
@Test
void extractApiSpecJsonFile() throws Exception {
File file = new File(filename);
Path filePath = file.toPath();
if (file.exists()) {
Assertions.assertThat(file.isFile()).isTrue();
} else {
Path path = file.getParentFile().toPath();
if (Files.notExists(path)) {
Files.createDirectory(path);
}
if (Files.notExists(filePath)) {
Files.createFile(file.toPath());
}
}
mvc.perform(MockMvcRequestBuilders.get(apiDocJsonPath))
.andDo(
result ->
Files.write(file.toPath(), result.getResponse().getContentAsString().getBytes()));
}
}