Spring Boot quickly integrates Swagger

1, Foreword

As the most popular Java web development scaffold, Spring Boot is used by more and more developers to build enterprise RESTFul API interfaces. These interfaces will serve not only the traditional web side (b/s), but also the mobile side. In the actual development process, these interfaces should also be provided to the development and testing for relevant white box testing, so there is bound to be the problem of how to share and update API development interface documents in multi person cooperation.

Integrating documents with Swagger has the following advantages:

  • Rich functions  : Support multiple annotations, automatically generate interface documents, and test API interface functions on the interface;
  • Timely update  : Spend a little time writing comments in the development process, you can update API documents in time, which saves you worry and effort;
  • Simple integration  : By adding pom dependency and simple configuration, the API interface document interface can be published simultaneously when embedded in the application, and there is no need to deploy independent services.

Next, we use Spring Boot to integrate Swagger to realize the functions of online API documents. In this paper, we use SpringFox Swagger2, version 2.9.2 (the latest version is 3.0.0, but in my test, the swagger-ui.html page has not come out. In https://mvnrepository.com/ You can also see that 2.9.2 is the most used version at present)

2, Create Spring Boot project

The development tool I use is IDEA. I can quickly create a Spring Boot project through IDEA. When creating, just check the web dependency option. It doesn't matter if I don't check it. The configuration in pom.xml is the same later. Note that when creating a project, the project name should be lowercase.

Add two dependencies of Swagger

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3, Add configuration class

Add a swagger configuration class, create a new config package under the project, and add a SwaggerConfig configuration class SwaggerConfig.java.

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("on-line API file")
                .description("This is a restful api document of demo")
                .version("1.0")
                .build();
    }

}

The above has completed the configuration of Swagger. Is it very simple and easy.

4, Create a test Controller to verify the configuration

Add a controller, create a new controller package under the project, and add a HelloController.java.

package com.louis.springboot.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* Class annotation */
@Api
@RestController
public class HelloController {

    /* Method annotation */
    @ApiOperation(value = "desc of method", notes = "")
    @GetMapping(value="/hello")
    public Object hello( @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}

5, Compile and run tests

Start the project,   Open a browser to: http://localhost:8080/swagger-ui.html to enter the swagger interface document interface.

It's convenient to manage the API interface and update the code in real time. You don't have to worry about writing interface documents.

Appendix: Swagger common notes

API Use location
@Api Used on the controller class, indicating that this class is a resource of swagger
@ApiOperation It is used in the method of controller to represent the operation of an http request
@ApiParam Parameter annotation in method
@ApiResponses Used in the controller method
@ApiResponse Used in @ ApiResponses
@ApiImplicitParams Used in the controller method
@ApiImplicitParam Used in the @ ApiImplicitParams method
@ApiModel Used on the return object class

There are many problems encountered in WEB project development. If you want to know how to quickly master Spring Boot, please refer to the video:

51CTO: Developing small and complete web projects with Spring Boot+Bootstrap
Tencent Classroom: Developing small and complete web projects with Spring Boot+Bootstrap
CSDN College: Developing small and complete web projects with Spring Boot+Bootstrap
Netease cloud Classroom: Developing small and complete web projects with Spring Boot+Bootstrap

Tags: Spring Boot swagger

Posted on Tue, 09 Nov 2021 06:41:45 -0500 by jennatar