SpringBoot+Swagger2實現API文檔+lombok工具包簡化代碼

Swagger UI:提供了一個可視化的UI頁面展示描述文件。
接口的調用方、測試、項目經理等都可以在該頁面中對相關接口進行查閱和做一些簡單的接口請求。
該項目支持在線導入描述文件和本地部署UI項目。
lombok是一個可以幫助我們簡化java代碼編寫的工具類，尤其是簡化javabean的編寫，
即通過採用註解的方式，消除代碼中的構造方法，getter/setter等代碼，使我們寫的類更加簡潔

1、在項目中的pom.xml文件中加入maven依賴包

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>
		<!--lombok一個幫助我們簡化javabean代碼編寫的工具包-->
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<version>1.18.6</version>
			<scope>provided</scope>
		</dependency>

2、添加Swagger配置類Swagger2Config

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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;

@Configuration
// 可指定配置文件，比如當使用prod生產環境的配置文件時該類不生效
@Profile({"dev", "test"})
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 爲當前控制層包路徑
                .apis(RequestHandlerSelectors.basePackage("com.pactera.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	
    /**
     * 構建 api文檔的詳細信息函數
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 頁面標題
                .title("用戶模塊服務")
                // 描述
                .description("接口文檔")
                .version("1.0")
                .build();
    }
}

3、在controller類中加上相應的註解

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// @Api註解是swagger裏的，主要爲類提供相關說明
@Api(tags = "人員控制層接口")
@RestController
@RequestMapping("/v1/user")
public class UserController {

	@Autowired
	private UserService userService;

	/**
	 * @ApiOperation註解是swagger裏的，主要爲接口提供相關說明
	 */
	@ApiOperation(value = "根據工號查看人員詳情")
	@PostMapping("/findUserDetailById")
	public ResultDto findUserDetailById(@RequestParam("userId") String userId) {
		return userService.findUserDetailById(userId);
	}
	
}

4、在啓動類中加入@EnableSwagger2註解

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class Application {

	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
	
}

啓動項目後，訪問http://localhost:8080/swagger-ui.html 看看顯示效果：出現下面頁面則成功

當項目的靜態文件路徑被修改後，就會發生訪問不到的情況

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

Thu Aug 01 09:50:09 CST 2019
There was an unexpected error (type=Not Found, status=404).
No message available

因爲swagger-ui.html 是在springfox-swagger-ui.jar裏的，
因爲修改了路徑Spring Boot不會自動把/swagger-ui.html這個路徑映射到對應的目錄META-INF/resources/下面。
所以我們修改SpringBoot配置類，爲Swagger建立新的靜態文件路徑映射就可以了

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
@EnableWebMvc
public class WebMvcConfig extends WebMvcConfigurerAdapter {

	@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

可以在實體類的類名上加入@ApiModel，變量使用@ApiModelProperty

@ApiModel作爲類的描述
@ApiModelProperty作爲字段的描述
@Data 註解相當於 Getter + Setter + ToString + @RequiredArgsConstrutor
需要注意的是：@ApiModel內的註釋不要出現相同否則會將相同的vo內的字段進行合併

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel(value = "User", description = "人員信息描述")
@Data
public class User {
    
    @ApiModelProperty("工號")
    private String userId;
    
    @ApiModelProperty("姓名")
    private String userName;
    
}