OpenAPI, formerly known as Swagger, is a widely used specification for defining APIs. Converting an OpenAPI 2.0 (Swagger 2.0) specification to OpenAPI 3.0 is essential for leveraging the new features and improvements in OpenAPI 3.0. This article will explore the differences between OpenAPI 2.0 and OpenAPI 3.0, set up a sample project using the publicly available Petstore API, and demonstrate how to perform the conversion using various tools. Let us delve into how to upgrade from OpenAPI 2 to OpenAPI 3 in Java.
1. Differences Between OpenAPI 2.0 and OpenAPI 3.0
OpenAPI 3.0 introduces several enhancements over OpenAPI 2.0:
- Components Section: OpenAPI 3.0 introduces a
componentssection that replacesdefinitions,parameters, andresponsesfrom OpenAPI 2.0. This section centralizes reusable components like schemas, parameters, and responses. - Request Bodies: OpenAPI 3.0 provides a dedicated
requestBodyobject, allowing more expressive and flexible request body definitions compared to the OpenAPI 2.0parameterssection. - Improved Data Types: OpenAPI 3.0 adds support for
oneOf,anyOf, andnotin schema definitions, enhancing JSON schema support. - Links and Callbacks: New features like
links(describing relationships between operations) andcallbacks(describing asynchronous APIs) are introduced in OpenAPI 3.0. - Improved Security Definitions: Security definitions are more flexible, with better support for OAuth 2.0 and OpenID Connect.
A comprehensive list of the changes can be found in the OpenAPI Specification releases.
2. Sample Project Setup with Petstore API
For our sample project setup, we will use the publicly available Petstore API, accessible at https://petstore.swagger.io/v2/swagger.json, as a demonstration example. To obtain the OpenAPI 2.0 specification file, right-click the link and choose “Save Link As…” to download the swagger.json file to your local system. This specification will serve as the base for our conversion and migration examples.
3. Conversion Using Various Tools
The following sections demonstrate how to convert an OpenAPI 2.0 specification to OpenAPI 3.0 using different tools.
3.1 Swagger Editor Online Converter
This web-based tool offers a user-friendly interface for conversion. To convert your OpenAPI 2.0 specification using the Swagger Editor, visit the online editor at editor.swagger.io. Import your OpenAPI 2.0 specification into the editor by pasting its content or uploading the previously downloaded swagger.json file.
Next, navigate to the “Edit” menu and select “Convert to OpenAPI 3.0.x” Once the conversion is complete, review the updated specification and download the converted OpenAPI 3.0 file for further use.
3.2 Using Swagger Codegen for OpenAPI 2.0 to 3.0 Conversion
Swagger Codegen is a tool for generating client and server code from API specifications, as well as for converting OpenAPI specifications. It offers flexibility and extensive support for multiple programming languages and frameworks. To convert an OpenAPI 2.0 specification to OpenAPI 3.0 using Swagger Codegen, first download the latest swagger-codegen-cli JAR file from https://swagger.io/tools/swagger-codegen/ and save it in an easily accessible directory on your system.
Then, open a terminal or command prompt, navigate to the directory containing the swagger-codegen-cli.jar file, and run the conversion command. Adjust the file paths and arguments as needed to specify the input file (your OpenAPI 2.0 specification), output format, and target directory.
java -jar swagger-codegen-cli-3.0.64.jar generate -i path/to/swagger.json -l openapi-yaml -o path/to/output-directory
-i: Specifies the input file, which is your OpenAPI 2.0 specification (swagger.json).-l: Sets the language or format for generation. For conversion, useopenapi-yamlto output the OpenAPI 3.0 specification in YAML format. To convert to JSON format, use the-l openapioption.-o: Specifies the output directory for the converted files.
3.3 Using OpenAPI Generator
The openapi-generator-cli is a versatile tool that supports converting OpenAPI 2.0 specifications to OpenAPI 3.0 as part of its workflow, alongside generating code for multiple programming languages. To get started, you can download the latest version directly or install the CLI tool globally for convenience.
npm install @openapitools/openapi-generator-cli -g
To generate code and perform the conversion, run the following command:
openapi-generator-cli generate \ -i https://petstore.swagger.io/v2/swagger.json \ -g openapi \ -o openapi3-converted
3.4 Swagger Converter
Swagger Converter provides an efficient tool for converting OpenAPI 2.0 specifications to OpenAPI 3.0, offering both an API and a user-friendly web interface for easy access. Swagger Converter is accessible through its online platform at https://converter.swagger.io/. This allows users to easily upload their OpenAPI 2.0 specification files and convert them into OpenAPI 3.0.
Swagger Converter also provides an API endpoint for converting OpenAPI 2.0 (Swagger 2.0) specifications to OpenAPI 3.0 format. The conversion can be performed by sending a POST request with the OpenAPI specification content to the Swagger Converter API. We can use curl or any HTTP client library to send the OpenAPI 2.0 specification to the Swagger Converter API for conversion.
Let’s assume we have the OpenAPI 2.0 specification (swagger.json) that we want to convert. Here is how we can send a POST request to convert the specification using curl:
curl -X POST "https://converter.swagger.io/api/convert" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-binary @swagger.json \
-o converted-openapi3.json
- POST Request: Sends the OpenAPI 2.0 specification to the API for conversion.
@swagger2.json: Refers to the OpenAPI 2.0 JSON specification file you want to convert. Replace it with the path to your file.-o converted-openapi3.json: Outputs the converted OpenAPI 3.0 specification to a file namedconverted-openapi3.json.
4. Conclusion
In this article, we explored the process of the OpenAPI2 to OpenAPI3 upgrade in Java, covering key differences between the two versions and the tools available for conversion. We demonstrated how to use tools like Swagger Editor, Swagger Codegen, and openapi-generator-cli to seamlessly convert OpenAPI 2.0 specifications to OpenAPI 3.0.
In conclusion, converting OpenAPI 2.0 to OpenAPI 3.0 is straightforward with the help of tools like Swagger Editor, Swagger Converter, Swagger Codegen, and openapi-generator-cli. Each tool provides unique features to help us migrate and take advantage of OpenAPI 3.0’s new capabilities.
This article focused on how to upgrade OpenAPI2 to OpenAPI3 in Java.
