The OpenAPI 3.0 specification has been around for a while now but to date I’ve still been using its predecessor — the Swagger 2.0 definition. For a new project I decided to define the REST API using the OpenAPI 3.0 definition and feed that into some of the excellent tooling provided by Swagger to generate a Spring based Java project to help kickstart the implementation.
Swagger 2.0 vs OpenAPI 3.0
The good news for those that are familiar with Swagger 2.0 is that the changes made for OpenAPI 3.0 are backwards compatible in a functional sense, although your JSON or YAML file will need to be updated as the format has changed a little (tools such as the Mermade Swagger 2.0 to OpenAPI 3.0.0 converter are available to do this for you).
Some of my favourite enhancements added in OpenAPI 3.0 are;
Pi Weather REST API
The project I’m currently exploring is all about building and implementing a small grid of Raspberry Pi based sensors to collect weather measurements from various locations and to provide a dashboard to display the data. As part of this system there will be a REST API to read and write the measurements. The write API will be called by each Raspberry Pi that is collecting weather measurements. The read API will be called by the Raspberry Pi which is running the dashboard application.
This simple REST API is described below in the following OpenAPI 3.0 JSON file:
Generating Spring Project
Now we have the REST API defined we can use the Swagger Codegen tool to create a skeleton Spring based Java project to implement it. Depending on your operating system there are different ways to install this, ranging from Homebrew, to downloading the latest stable JAR from Maven, to cloning the repo and building it yourself.
The only warning I would give is to ensure you are using the 3.x version of the tool since this is required in order to support OpenAPI 3.0 and later. The 2.x version of the tool only supports Swagger 2.0 and gives misleading errors if it’s run against OpenAPI 3.0 files.
Once everything has been installed, we only need to create an options file allowing us to specify the Java package name and then we’re ready to go. Running the tool itself takes a few options:
I’ve put these options together into a small script (see my GIT repo https://github.com/arronharden/pi-weather-api-swagger30) which will download the Swagger Codegen JAR from Maven and run it against my OpenAPI 3.0 definition:
Generated Java Spring Project
Now we have the skeleton project generated we can import it into our favourite IDE and start implementing the logic for each of the APIs.
One nice touch with the Spring code generator is that the skeleton code it creates will return any example JSON content we provided in the OpenAPI 3.0 definition together with a 501 status, which means we can quickly run it up and try out some of the GET APIs. Here’s an example of running Postman against the newly generated project.
We’ve looked at some of the changes added into OpenAPI 3.0 and seen what a new REST API definition looks like. Using the Swagger Codegen tool we’ve also generated a skeleton Spring based Java project ready to have the real implementation created for the REST API endpoints.
This content was originally published here.