Migration from Swagger 2 to OpenAPI 3

A lot of API are documented using Swagger, it’s a good thing that API are documented four us dev for understanding how they work and how to call them.
But a lot of these API are documented using Swagger 2, now that OpenApi is released (since 2017, the actual version is the 3.1 and is available since 15/02/2021) some projects didn’t update their documentation tools, I will try in this article to help you do so.

What you will need

In order to follow this tutorial, you will need a REST API, so you can :

• Follow the tutorial to built your API and the one to documente it

• Clone the swagger branch of this repository

• Having your own API documented using Swagger 2 ready

Step 1 : getting ride of SpringFox dependencies

When we first implemented our Swagger, we add these dependencies to have

• The json generated at http://localhost:8080/v2/api-docs

• The UI at http://localhost:8080/swagger-ui.html

• The Bean Validation
  

  We will not need it anymore, so you can suppress them from your pom.xml. Those 3 dependencies will be replaced by just one
  With just this dependency we will have:

• The json generated http://localhost:8080/v3/api-docs/

• The UI page http://localhost:8080/swagger-ui.html

• The bean validation

At this point, we should have some compilation problems because of some annotations due to the missing dependencies that we have replaced.
We will corrige that now.

Step 2: changing the annotations of the endpoints

In the previous tutorial, we documented our API using a configuration class

Here we have 2 choices

• declaring a new configuration class

• Using annotations in one of our controllers

I will give you 2 equivalent example of the previous code in OpenApi way

Configuration class

With annotations

What it will look like in the UI

The previous example will look the same in the UI page, so it’s up to you to choose what method you want to use

Step 3: changing the annotations of the endpoints

Swagger 2.0 annotation

Let’s take an example

Here is a POST method documented with classique Swagger 2 annotations

• @ApiOperation : Describes an operation or typically a HTTP method against a specific path.

• @ApiResponses : A wrapper to allow a list of multiple ApiResponse objects. Here I have 2 @ApiResponse to describe my 200 and 500 HTTP status return code.
  I can also describe what my status will return, the 200 will respond with an objet, so I added the object class to response field.

That will render like the following picture in the UI page

Here a second example with this time a GET method

Here in addition of the previous annotations, I have added the documentation of the method parameter using @ApiParam.

With the new dependency, the annotation described are no longer the same.
So let’s see what has changed.

OpenAPI annotations

With the 2 above example who is the same method that i used previously we can now see some of the changes that was operated.

• @ApiOperation *-> *@Operation, the value field become summary and notes *become *description.

• @ApiResponse : the field code become responseCode and is no longer an integer but a string, also the field message become description.
  The biggest change is that the response field is now an annotation. @content.

• @ApiParam become @Parameter

They are other change, but since they are not used here, i recommend you to use the openAPI documentation.

Step 4: changing the annotations of the models

Swagger 2.0 annotation

So in Swagger 2 when i wanted to document an object, my class looked somewhere like this

As you can see, my classe is annoted with the @ApiModel and it’s properties with @ApiModelProperty.
*The *@ApiModelProperty allow us to add definitions such as description (value), name, data type, example values, and allowed values.

OpenAPI annotations

If you look closely at my ApiResponse with status code 200, you will see that the response is now @content, and that we gave the schema field the class that will be returned like this @Schema(implementation = MyClass.class).
With that annotation, OpenApi know which class to load, so i don’t have to annotate my class with an @ApiModel like annotation, but I still can document my property.

So, what I have done here ?
Like previously, my fields are documented, but I have used 2 differentes method for some validation (size).

I can use the bean validation annotation, or I can use the property of the Schema annotation, the result will be the same.

The position property don’t exist anymore, the fields are in the same order as the class.

Thanks for your reading time, as previously, the code used in this tutorial is findable in this Github repository, branch toOpenApi.