Generate OpenApi spec (json) as part of the build

[abedurftig]

Rather than the OpenApi spec only being available at runtime, it would be beneficial to be able to generate the OpenApi spec at build/compile time, so the spec could be stored as an artefact.

As far as I understand the Maven plugin, it will actually start the server during the integration test phase and then read and store the spec. I think this is not always helpful, because sometimes a service cannot be started without any further configuration (Properties, Environment Variables, etc.).

[bnasslahsen]

The necessary metadata for the OpenAPI spec are only available on runtime, which explains the choice of generation at runtime.

If you feel you have a better proposal, please feel free to contribute with a PR.

[davidhsv]

@abedurftig I managed to make it part of my mvn install, generating the swagger.json on test time:

@RunWith(SpringRunner.class)
@SpringBootTest
public class GenerateSwagger {

    @Autowired
    WebApplicationContext context;

    @Test
    public void generateSwagger() throws Exception {
        MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(context).build();
        mockMvc.perform(MockMvcRequestBuilders.get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andDo((result) -> {
                    FileUtils.writeStringToFile(new File("swagger.json"), result.getResponse().getContentAsString());
                });

    }
}

[samarthpatil619]

@davidhsv
I tried to implement your code but it gives me
junit.framework.AssertionFailedError: Exception in constructor: testApp (java.lang.IllegalArgumentException: WebApplicationContext is required
at org.springframework.util.Assert.notNull(Assert.java:201)
at org.springframework.test.web.servlet.setup.DefaultMockMvcBuilder.(DefaultMockMvcBuilder.java:52)
at org.springframework.test.web.servlet.setup.MockMvcBuilders.webAppContextSetup(MockMvcBuilders.java:47)
at com.thegoldensource.ui.restservice.AppTest.(AppTest.java:34)
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)

as WebApplicationContext context is null so how didi u did it.

please help

[davidhsv]

Hi @samarthpatil619,

The WebApplicationContext is null probably because the Spring context hasn't been initialized correctly. Let's try a couple of things to address this.

1. Please ensure that your test class resides in the same package (or a subpackage) as your main Spring Boot application class or at least ensure that your main Spring Boot application class is properly scanned by Spring.

2. The annotation @SpringBootTest should be able to set up a full Spring application context along with all of the beans and the WebApplicationContext. But if it's not, you can specify the classes the application context should be initialized with by using the classes attribute of the @SpringBootTest annotation.

@SpringBootTest(classes = YourSpringBootApplication.class)

Where YourSpringBootApplication is your main Spring Boot application class. This should ensure that the Spring Boot test framework correctly creates the application context for your test.

If you're still facing the issue, please provide more details about your Spring Boot application's configuration and your test setup, so I can assist you better.

Best,
David

[samarthpatil619]

Hii @davidhsv

I am not using spring boot application a normal springmvc project.

so this is my code and want to initialise this WebApplicationContext as it gives null.

public class AppTest
extends TestCase
{
@Autowired
private WebApplicationContext context;

public AppTest( String testName ) throws Exception
{
    super( testName );
    MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();
    mockMvc.perform(MockMvcRequestBuilders.get("/v3/api-docs").accept(MediaType.APPLICATION_JSON))
            .andDo((result) -> {
                FileUtils.writeStringToFile(new File("swagger.json"), result.getResponse().getContentAsString());
            });
}

}

Is there any way i could get this openapi json /ymal at compile time .

[davidhsv]

Hi @samarthpatil619,

The issue appears to be with the setup of your test class. When you are not using Spring Boot, you need to manage the configuration and setup of the Spring context yourself.

Firstly, ensure your application is correctly configured for Spring MVC and the classes have been annotated with @Controller or @RestController where appropriate.

Here's an example of what your setup might look like:

import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import java.io.File;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;

@RunWith(SpringJUnit4ClassRunner.class)
@WebAppConfiguration
@ContextConfiguration("file:src/main/webapp/WEB-INF/spring-mvc-servlet.xml")
public class AppTest {

    @Autowired
    private WebApplicationContext wac;

    private MockMvc mockMvc;

    @Before
    public void setup() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
    }

    @Test
    public void generateSwagger() throws Exception {
        this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andDo((result) -> {
                    FileUtils.writeStringToFile(new File("swagger.json"), result.getResponse().getContentAsString());
                }).andReturn();
    }
}

Note: Replace "file:src/main/webapp/WEB-INF/spring-mvc-servlet.xml" with your Spring configuration file path.

This test class uses @RunWith(SpringJUnit4ClassRunner.class), @WebAppConfiguration, and @ContextConfiguration to setup the Spring context and inject the WebApplicationContext. The @Before annotated method is used to setup MockMvc before each test.

Regarding your second question, about getting the OpenAPI json/yaml at compile time, currently, it's not possible with Spring MVC. Swagger (or OpenAPI) JSON/YAML are generally generated at runtime since they are based on the running application state. They can depend on various runtime factors like Spring profiles, conditional beans, etc. For compile-time API documentation, you may need to explore different tools or methodologies.

Hope this helps. Let me know if you have further queries.

Best,
David