How to Convert OpenAPI 2.0 to OpenAPI 3.0 in Java

1. Introduction

Although the OpenAPI 3.x Specification has been available since 2017 and has gone through several updates, many APIs continue using older versions.

In this tutorial, we’ll explore the key differences between OpenAPI 2.0 and OpenAPI 3.0 specifications and learn different methods for upgrading from the older to a more recent version.

2. OpenAPI 2.0 vs. OpenAPI 3.0

To briefly review, OpenAPI provides a standard format for describing HTTP APIs readable to humans and machines. Before version 3.0, the OpenAPI was known as a Swagger Specification and a part of the Swagger toolkit. Since then, it has become an industry standard, with several updates, bringing additional improvements and features.

Compared to 2.0, OpenAPI 3.0 introduced several fundamental changes.

First, the overall structure has been rearranged to improve reusability. A components block was added to organize existing elements, such as schemas, responses, parameters, and new ones – requestBody, examples, and headers. Some elements were renamed – definitions are now called schemas, and securityDefinitions are securitySchemes.

Additionally, OpenAPI 3.0 extended the JSON Schema features further. Keywords such as oneOf, anyOf, and not were added to allow description and flexible validation of complex data formats.

Next, version 3.0 introduced support for cookie parameters, content type negotiation, and a callback mechanism. It also expanded its security definitions and simplified existing flows.

To conclude, the complete list of changes is available in the official changelog.

3. Project Setup

Let’s move on to setting up a project. Typically, we’d expose the REST service and use OpenAPI to define and document the API. However, since we’ll be converting a 2.0 version of OpenAPI specification to a newer one, let’s use a publicly available API.

While the YAML specification version is also available, we’ll focus on the JSON format. So, let’s download the file and place it in our resources folder. That way, it’ll be easily accessible for demonstrating the different ways of transforming the specification. Depending on the method, we’ll upload the file via browser or curl, pass it as a parameter, or reference it in code.

4. Tools and Libraries

There are various tools and libraries to choose from when working with OpenAPI specifications. Let’s start by reviewing options that don’t require local installation, allowing us to convert API specification versions directly in a browser.

4.1. Swagger Editor

Among other functionalities, Swagger Editor allows us to upload or paste the API specification and convert it to OpenAPI 3.0 or other formats. Let’s provide the specification, select Convert to OpenAPI 3 from the menu under the Edit option, and wait for the conversion to complete:

Once finished, the new version of the specification is automatically available.

4.2. Swagger Converter

Moving on, the online version of the Swagger Converter tool provides two methods for converting specifications.

This first one allows the OpenAPI 2.0 specification to be provided directly, either by uploading a file or pasting the JSON content:

curl -X 'POST' \
 'https://converter.swagger.io/api/convert' \
 -H 'accept: application/json' \
 -H 'Content-Type: application/json' \
 --data-binary @swagger.json

If the API is publicly accessible, we can convert the specification by referencing a URL that points to the older version of the API specification:

curl -X 'GET' \
'https://converter.swagger.io/api/convert?url=https%3A%2F%2Fpetstore.swagger.io%2Fv2%2Fswagger.json' \
-H 'accept: application/json'

Swagger Converter supports JSON and YAML formats, and a user-friendly UI is available for easier conversion.

4.3. API Spec Converter

In the case of the public APIs, another option is the api-spec-converter, an open-source library that supports various API specification formats. Let’s provide a URL, select OpenAPI 2 (Swagger) as a Source and OpenAPI 3.0 as a Destination Format, and click Convert:

Upon successful completion, the converted specification will be available for download.

Let’s now explore other tools that have CLI and plugin versions.

4.4. Swagger Codegen

The Swagger Codegen is an open-source code generator. Besides creating REST clients, generating server stubs, and API documentation in various formats, we can use the library to convert specifications.

Let’s download the latest version and execute the following command:

java -jar swagger-codegen-cli-3.0.62.jar generate \
  -l openapi \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o converted

The result is the OpenAPI 3.0 specification located in the specified output folder (in our case, converted).

By choosing different command line options, we can customize the generation process. For instance, in the example above, a language (-l or –lang) set to openapi will produce JSON. To get the specification in YAML format, we need to set it to openapi-yaml.

4.5. OpenAPI Generator

The conversion process looks similar if we use OpenAPI Generator since it’s a fork of Swagger Codegen. Using the latest version, let’s run the command below:

java -jar openapi-generator-cli-7.9.0.jar generate \
  -g openapi \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o converted

Again, we can generate specifications in YAML or JSON format by choosing different generator name (-g) options, such as openapi-yaml or openapi.

It’s important to note that the Java versions must be compatible when running the JAR files in the CLI. Otherwise, we may encounter an UnsupportedClassVersionError, which indicates the version mismatch.

4.6. Swagger Parser

As the name suggests, Swagger Parser helps us parse the OpenAPI documents. Moreover, we can use it to convert the old version of the specification to a new one.

Following instructions for using the Swagger Parser, let’s create a simple method for processing specification files:

private static OpenAPI processSpecificationJson(final String specificationFileLocation) {
    SwaggerParseResult result = new OpenAPIParser().readLocation(specificationFileLocation, null, null);
    final OpenAPI openAPI = result.getOpenAPI();
    if (openAPI == null) {
        throw new IllegalArgumentException("Failed to parse OpenAPI specification from: " 
          + specificationFileLocation);
    }
    return openAPI;
}

Next, we can use the ObjectMapper‘s writeValueAsString() method to serialize OpenAPI objects as JSON:

private static String asJsonString(OpenAPI openAPI) throws JsonProcessingException {
    return objectMapper.writerWithDefaultPrettyPrinter()
      .writeValueAsString(openAPI);
}

By setting the corresponding properties, we made the JSON output more readable and excluded the null values:

private static final ObjectMapper objectMapper;
static {
    objectMapper = new ObjectMapper();
    objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
}

At this point, we can define the conversion method:

public static String convert(String specificationFileLocation) throws IOException {
    if (specificationFileLocation == null || specificationFileLocation.isEmpty()) {
        throw new IllegalArgumentException("Specification file path cannot be null or empty.");
    }
    return asJsonString(processSpecificationJson(specificationFileLocation));
}

Finally, our test verifies the conversion process by ensuring that the result isn’t null:

@Test
void givenOpenApi2_whenConvert_thenSpecificationSuccessfullyConverted() throws IOException {
    String openAPI3 = SwaggerToOpenApiConverter.convert(FILE_OPEN_API_2_SPECIFICATION);
    assertNotNull(openAPI3);
}

A successful test indicates that OpenAPI 2 was correctly converted.

5. Conclusion

In this tutorial, we demonstrated a couple of options for converting OpenAPI 2.0 specifications to OpenAPI 3.0. We explored various tools and libraries, including online options like Swagger Editor and Converter and command-line tools such as Swagger Codegen and OpenAPI Generator.

Since they offer similar conversion functionalities, our choice depends on whether or not the API is publicly available, our familiarity with the tools, and the additional features we need to implement.

As always, the complete source code is available over on GitHub.