Swagger 3.0 has been around for a while, it was released in July 2019, but currently the mainstream version in use is Swagger 2.x and a small amount of 1.x, but how can a qualified programmer not fidget with new technology? So here’s a look at the latest version of Swagger. In this article, we will take a look at what changes can be made to the new version of Swagger. How do you upgrade the old Swagger to the new one?

What’s a Swagger?

Swagger is a Web service for generating, describing, and invoking RESTful interfaces. In layman’s terms, Swagger is a service that puts all of a project’s interfaces (you want to expose) on the page and can be invoked and tested.

PS: Swagger follows the OpenAPI specification, a Linux Foundation project that attempts to standardize RESTful service development processes by defining a language for describing API formats or API definitions.

Swagger website address: swagger. IO /

What’s the use of Swagger?

From the definition above, we can see that a Swagger has three important functions:

  1. Presenting all the interfaces in your project on a page so that back-end programmers don’t have to write interface documents specifically for front-end users;
  2. When the interface is updated, you can simply modify the Swagger description in the code to generate a new interface document in real time, thereby avoiding the problem that the interface document is too old to be used.
  3. With the Swagger page, we can make interface calls directly, reducing the cost of debugging during the development phase of the project.

Swagger Used in older versions

Swagger 2.9.2: Swagger 2.9.2: Swagger 2.9.2: Swagger 2.9.2

Swagger 2.9.2 can be used in four steps:

  1. Add the dependent
  2. Turn on the Swagger feature
  3. Configure Swagger document summary information
  4. Call interface access

Let’s look at them separately.

1. Add a dependency

First, go to mvnRepository and search for Swagger’s dependencies. Search for “Springfox” keyword and get the first two dependencies in the result, as shown in the figure below:Add these two dependencies to the tape project:

<! -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.92.</version> </dependency> <! -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.92.</version>
</dependency>
Copy the code

Why “Springfox”?

Q: Why search for “Springfox” when we’re using Swagger?

A: Swagger can be seen as a technology that follows the OpenAPI specification, and SpringFox is a concrete implementation of that technology. Just like AOP and DI in Spring, the former is the idea, while the latter is the implementation.

2. Open the Swagger

Add the @enableswagger2 annotation to the Spring Boot Boot class or configuration class to open the Swagger. Some core code is as follows:

@EnableSwagger2
@SpringBootApplication
public class Application {...
Copy the code

3. Configure summary information

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(a) {
        return new Docket(DocumentationType.SWAGGER_2) // 1.SWAGGER_2
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller")) // 2. Set the scan path.build(); }}Copy the code

4. Visit the Swagger

After the project starts normally, use”http://localhost:8080/swagger-ui.html “Swagger page, as shown in the figure below:

The latest version of Swagger uses

The configuration steps for the latest version of Swagger are the same as for the older version, but each configuration item is slightly different. Here are the steps:

1. Add a dependency

<! -- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
Copy the code

As you can see from the configuration above, the new version of Swagger has only one dependency, while the old version has two, which is also much cleaner.

2. Open the Swagger

Add the @enableOpenAPI annotation to Spring Boot’s Boot class or configuration class to open the Swagger. Some core code is as follows:

@EnableOpenApi
@SpringBootApplication
public class Application {...
Copy the code

3. Configure summary information

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(a) {
        return new Docket(DocumentationType.OAS_30) / / v2
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // Set the scan path.build(); }}Copy the code

As you can see from the code above, only the document type setting is different in the Docket configuration. The new version is OAS_30 and the old version is SWAGGER_2.

PS: OAS is short for OpenAPI Specification, translated into Chinese is OpenAPI Specification.

4. Visit the Swagger

The new version of the Swagger access address is different from the old version of the address, the new version of the access address is “localhost:8080/swagger-ui/”, as shown below:

New VS old

The differences between the new version and the old version are mainly reflected in the following four aspects:

  1. Dependencies are added differently: the new version only needs to add one item, whereas the old version needs to add two items;
  2. Boot Swagger’s notes differently: the new version uses is@EnableOpenApi, while the old version is@EnableSwagger2;
  3. The file type configuration for Docket (document summary information) is different: the new version isOAS_3, while the old version isSWAGGER_2;
  4. Swagger UI access address different: the new version to access the address is “http://localhost:8080/swagger-ui/”, and the old version to access the address is “http://localhost:8080/swagger-ui.html”.

conclusion

The new Swagger has two impressive features: Simpler configurations, such as 50% fewer dependencies, and a lot of changes to the page design, which makes the pages feel more modern, more technical, and generally better looking.

It’s worth noting that the entire Swagger upgrade process is smooth. Simple configuration is all it takes to go from the old version to the new one, and the annotations that describe the interface continue to use the old version, making it possible to get to the latest version without having to change most of the major code.

Swagger 3 Swagger 3