Skip to main content

Static Generation

Users tend to start out with running Springwolf at runtime as part of the Spring Boot application context. Still, it's possible to generate the AsyncAPI documentation statically at build time.

One use-case is to protect against unexpected API changes using a test. For this, the expected asyncapi.json file is stored in the VCS repository.

Spring Boot Test (full spring context)

The most simple way is a Spring Boot test (taken from springwolf-kafka-example):

@SpringBootTest(
classes = {SpringwolfKafkaExampleApplication.class},
webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ApiIntegrationTest {

@Autowired
private TestRestTemplate restTemplate;

@Test
void asyncApiResourceArtifactTest() throws IOException {
// given
String url = "/springwolf/docs";

// when
String actual = restTemplate.getForObject(url, String.class);

// then
// writing the actual file can be useful for debugging (remember: .gitignore)
Files.writeString(Path.of("src", "test", "resources", "asyncapi.actual.json"), actual);

// then
InputStream s = this.getClass().getResourceAsStream("/asyncapi.json");
String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim();
assertEquals(expected, actual);
}
}

Springwolf Standalone (minimal spring context)

Especially for large application, starting the full Spring Boot context can be slow. Springwolf standalone uses a minimal Spring application context, by only including beans and configurations marked with @StandaloneConfiguration.

Demo code (taken from springwolf-kafka-example):

class StandaloneTest {

@Test
public void asyncApiStandaloneArtifactTest() throws IOException {
// given
StandaloneApplication standaloneApplication =
DefaultStandaloneApplication.builder().buildAndStart();

// when
AsyncAPI asyncApi = standaloneApplication.getAsyncApiService().getAsyncAPI();
String actual = new DefaultAsyncApiSerializerService().toJsonString(asyncApi);

// then
// writing the actual file can be useful for debugging (remember: gitignore)
Files.writeString(Path.of("src", "test", "resources", "asyncapi.standalone.json"), actual);

// then
InputStream s = this.getClass().getResourceAsStream("/asyncapi.json");
String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim();
assertEquals(expected, actualPatched);
}
}

By default, only the io.github.springwolf package is scanned and @StandaloneConfiguration in other packages are not picked up. Use the DefaultStandaloneApplication.builder() to customize the Spring environment, load custom beans and configurations.

The application.properties configuration is picked up.

Gradle Plugin (full spring context)

You can use the springdoc-openapi-gradle-plugin and configure the plugin for Springwolf (taken from springwolf-kafka-example):

openApi {
apiDocsUrl = "http://localhost:8080/springwolf/docs"
outputDir = file("$buildDir/docs")
outputFileName = "asyncapi.json"
}

The plugin will start up the spring boot application by using the bootRun task and then try to download the documentation from the given apiDocsUrl and store it in the outputDir and with the given outputFileName.

If your application is unable to start up with the bootRun task, see if customBootRun properties can help you.