整合文档API Swagger2

整合文档API Swagger2

相关依赖

	<!-- swagger2 配置 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.4.0</version>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.4.0</version>
	</dependency>
	<dependency>
		<groupId>com.github.xiaoymin</groupId>
		<artifactId>swagger-bootstrap-ui</artifactId>
		<version>1.6</version>
	</dependency>

配置类

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    //http://localhost:8088/swagger-ui.html 原路径
    //http://localhost:8088/doc.html 原路径
    
    // 配置swagger2核心配置 docket
    @Bean
    public Docket createRestApi() {
	    return new Docket(DocumentationType.SWAGGER_2)  // 指定api类型为swagger2
				    .apiInfo(apiInfo()) // 用于定义api文档汇总信息
				    .select()
				    .apis(RequestHandlerSelectors
				    		.basePackage("com.robin.controller"))   // 指定controller包
				    .paths(PathSelectors.any()) // 所有controller
				    .build();
    }
    
    private ApiInfo apiInfo() {
	    return new ApiInfoBuilder()
			    .title("XXXX平台接口api")// 文档页标题
			    .contact(new Contact("robin","https://www.robin.com","abc@robin.com"))// 联系人信息
			    .description("专为xxxx平台提供的api文档")  // 详细信息
			    .version("1.0.1")   // 文档版本号
			    .termsOfServiceUrl("https://www.robin.com") // 网站地址
			    .build();
	}
}

优化显示

通过ApiIgnore注解来隐藏该controller，不在swagger文档中展示

@ApiIgnore
@RestController
public class HelloController {
}

通过@Api注解来给controller添加描述 @ApiOperation来给具体接口添加描述

@Api(value = "注册登录", tags = {"用于注册登录的相关接口"})
@RestController
@RequestMapping("passport")
public class PassportController {
	@ApiOperation(value = "用户名是否存在", notes = "用户名是否存在", httpMethod = "GET")
    @GetMapping("/usernameIsExist")
    public Result usernameIsExist(@RequestParam String username) {
    }
}

通过@ApiModel和@ApiModelProperty来给具体的参数添加描述

@ApiModel(value = "用户对象BO", description = "从客户端，由用户传入的数据封装在此entity中")
public class UserBO {
    @ApiModelProperty(value = "用户名", name = "username", example = "imooc", required = true)
    private String username;
    @ApiModelProperty(value = "密码", name = "password", example = "123456", required = true)
    private String password;
    @ApiModelProperty(value = "确认密码", name = "confirmPassword", example = "123456", required = false)
    private String confirmPassword;
}