As APIs evolve over time, it becomes essential to ensure backward compatibility and provide proper documentation for changes in different versions. This ensures that existing clients of the API can continue to access it without disruptions while new clients can leverage the latest features and improvements.

Versioning an API is a common practice in software development. It allows you to make changes to the API structure, response formats, or behavior while ensuring the existing clients do not break. There are several approaches to versioning APIs, such as using URL paths, request headers, or query parameters. In this blog post, we will focus on versioning APIs using URL paths and documenting them using Java Spring REST Docs.

Versioning APIs using URL Paths

One popular approach to API versioning is using URL paths. In this approach, the version number is included in the path, allowing different versions of the API to coexist. For example, consider an API with two versions, version 1 and version 2. The URLs for accessing different versions could be as follows:

• Version 1: GET /api/v1/users
• Version 2: GET /api/v2/users

By including the version number in the URL, clients can explicitly request a specific version of the API. This approach ensures backward compatibility by keeping the existing URLs intact and introducing new versions with separate paths.

Documenting API Versions with Java Spring REST Docs

Now let’s explore how we can document these API versions using Java Spring REST Docs. REST Docs allows us to generate concise and easy-to-understand documentation for our APIs, including the different versions.

To get started, we need to configure REST Docs in our Java Spring project. Add the following dependencies to your project’s pom.xml file:

<dependencies>
    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-core</artifactId>
        <version>2.0.4.RELEASE</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <version>2.0.4.RELEASE</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Next, we need to create a configuration class to enable REST Docs and provide additional customization. Create a class named ApiDocumentationConfig and add the following code:

import org.springframework.boot.test.autoconfigure.restdocs.RestDocsMockMvcConfigurationCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationConfigurer;

@Configuration
public class ApiDocumentationConfig {
    
    @Bean
    public RestDocsMockMvcConfigurationCustomizer restDocsMockMvcConfigurationCustomizer() {
        return configurer -> configurer.operationPreprocessors()
                .withRequestDefaults(prettyPrint())
                .withResponseDefaults(prettyPrint())
                .and().uris().withScheme("http").withHost("api.example.com");
    }
}

In this configuration class, we enable pretty printing for request and response bodies. We also set the host and scheme for generating accurate documentation URLs.

Now, let’s create a test class to document our API version. Create a class named UserControllerDocumentationTest and add the following code:

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.requestParameters;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.snippets;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.request;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
import org.springframework.test.web.servlet.MockMvc;

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs
public class UserControllerDocumentationTest {

    @Autowired
    private MockMvc mockMvc;

    private RestDocumentationResultHandler documentationHandler;

    @BeforeEach
    public void setUp() {
        this.documentationHandler = document("{class-name}/{method-name}",
                snippets(
                        requestParameters(
                                parameterWithName("version").description("API version")
                        )
                )
        );
    }

    @Test
    public void getUsersByVersion() throws Exception {
        this.mockMvc.perform(get("/api/{version}/users", "v1"))
                .andDo(this.documentationHandler)
                .andReturn();
    }

}

In this test class, we utilize REST Docs snippets to document our API versions. With requestParameters snippet, we document the version parameter in the request URL path.

By running this test, REST Docs generates API documentation in a human-readable format. You can customize the generated documentation by adding additional snippets for request and response fields, example requests/responses, etc.

With API versioning and comprehensive documentation in place, you can confidently evolve your APIs while maintaining backward compatibility. Clients can refer to the documentation to seamlessly transition to newer versions when they are ready.

Conclusion

API versioning is an important aspect of developing and maintaining APIs. By properly versioning and documenting your APIs, you can ensure that existing clients are not disrupted while allowing new clients to benefit from the latest features. Java Spring REST Docs provides a powerful toolset for generating comprehensive API documentation, including different API versions. By following the steps outlined in this blog post, you can effectively manage API versioning and provide clear documentation for consumers of your APIs.

#hashtags: #APIVersioning #Documentation