SpringBoot+Swagger2 整合

SpringBoot+Swagger2四步整合

第一步：添加相關依賴

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.9.RELEASE</version>
</parent>

<properties>
    <swagger2.version>2.7.0</swagger2.version>
</properties>

<dependencies>
    <!--springBoot 相關依賴-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!--swagger2 相關依賴-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger2.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger2.version}</version>
    </dependency>

</dependencies>

創建SrpingBoot啟動類

/**
 * Springboot+Swagger整合啟動類
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@SpringBootApplication
public class SwaggerApplication {

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

第二步：配置Swagger2

注意添加@Configuration EnableSwagger2注解

/**
 * Swagger2 接口Api文檔 配置文件
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 初始化創建Swagger Api
     */
    @Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				// 詳細信息定制
				.apiInfo(apiInfo())
				.select()
				// 指定當前包路徑
				.apis(RequestHandlerSelectors.basePackage("com.fame.controller"))
				// 掃描所有 .apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
	}

	/**
	 * 添加摘要信息
	 */
	private ApiInfo apiInfo() {
		// 用ApiInfoBuilder進行定制
		return new ApiInfoBuilder()
				.title("標題：springBoot-Swagger2整合學習")
				.description("描述：文檔構建器")
				.contact(new Contact("Fame-springBoot-Swagger2", null, null))
				.version("版本號: 1.0")
				.build();
	}
}

springfox為我們提供了一個Docket（摘要的意思）類，我們需要把它做成一個Bean注入到spring中，
顯然，我們需要一個配置文件，並通過一種方式（顯然它會是一個注解）告訴程序，這是一個Swagger配置文件。

springfox允許我們將信息組合成一個ApiInfo的類，作為構造參數傳給Docket（當然也可以不構造這個類，而直接使用null，但是你的這個API就太low了）。

第三步：創建測試實例

/**
 * Swagger接口測試
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@RestController
public class UserController {

    @GetMapping("/get")
    public String get(){
        return "Hello Swagger2";
    }
}

第四步：輸入SwaggerUI地址

http://localhost:8080/swagger-ui.html

Swagger2基本使用-常用注解

接口/方法常用注解

/**
 * Swagger接口測試
 * 
 * @author Y.yang
 * @date 2019/3/12
 */
@Api(value = "用戶信息", tags = { "用戶信息" })
@RestController
public class UserController {

	@ApiOperation(value = "用戶信息分頁查詢")
	@GetMapping("/page")
	public String page(User user) {
		return "Hello Swagger2";
	}

	@ApiOperation(value = "用戶信息查詢")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Integer"),
		@ApiImplicitParam(name = "file", value = "文件導入", required = true, dataType = "MultipartFile")
	})
	@GetMapping("/id")
	public UserVo getUser(Long id, MultipartFile file) {
		return new UserVo();
	}
}

@Api: 描述類/接口的主要用途

用於類；表示標識這個類是swagger的資源
tags–表示說明
value–也是說明，不會顯示在接口文檔上，可以使用tags替代

但是tags如果有多個值，會生成多個list

@Api(value = "用戶信息", tags = { "用戶信息" })

@ApiOperation: 描述方法用途

@ApiOperation(value = "用戶信息分頁查詢")

@ApiImplicitParam: 描述方法的參數

@ApiImplicitParams: 描述方法的參數(Multi-Params)

@ApiImplicitParams({
	@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Integer"),
	@ApiImplicitParam(name = "file", value = "文件導入", dataType = "MultipartFile")
})

實體類常用注解

/**
 * 用戶信息 數據傳輸對象 Dto（Data Transfer Object）
 * 
 * @author Y.yang
 * @date 2019/3/29
 */
@ApiModel(description = "用戶信息請求對象")
@Data
public class User implements Serializable {

	private static final long serialVersionUID = -6986638131456347054L;

	@ApiModelProperty(value = "姓名")
	private String username;

	@ApiModelProperty(value = "性別")
	private String sex;

	@ApiModelProperty(value = "年齡")
	private Integer age;

}

@ApiModel:描述實體類（Dto、Vo、Do等）

@ApiModel(description = "用戶信息請求對象")

@ApiModelProperty：描述實體類的字段

@ApiModelProperty(value = "姓名")