Swagger依赖
<!-- ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
@Configuration
@EnableSwagger2 //开启使用swagger2(swagger是老版的)
public class SwaggerConfiguration {//使用自定义配置
//使用docket实例用于取代swagger原本的配置。
@Bean
public Docket docket () {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("grp1")//设置分组
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
Contact DEFAULT_CONTACT = new Contact("作者名:zm", "指定的某个url", "作者email");
return new ApiInfo("标题:我的Swagger-Api文档",
"本文档描述信息", "版本:1.0",
"项目组织网址(一个url)",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
}
Swagger的配置详解
/**
* Docket对象说明
*/
// Docket构造对象说明
/**
1、DocumentationType, 案例类型,一般取 SWAGGER_2
2、ApiInfo(),用于配置swagger的外部描述信息,该对象仅有一个构造方法
3、enable(boolean):默认为true代表配置有效,可修改为false。
4、groupName(“grp1”):用于设置分组,同一配置类下可以有多个docket,每个docket拥有一个组。
5、select(), 使用docket对象的select()进行构造配置。
(1)apis():用于配置要扫描接口的方式,其接受参数是一个函数式接口:Predicate selector。
这里使用RequestHandlerSelectors.basePackage配置为扫描包:
示例:
RequestHandlerSelectors.basePackage("com.lk.controller") 扫描 com.lk.controller
RequestHandlerSelectors.withClassAnnotation(RestController.class) 扫描 RestController注解
(2)paths():用于配置过滤路径,其接受参数是一个函数式接口:Predicate selector。这里使用PathSelectors.ant(“/book/**”),表示筛选com.zm.controller包下访问接口为/book/下的接口。
示例:
PathSelectors.ant(“/book/**”) 访问接口为/book/路径的接口
PathSelectors.any() 扫描全部接口
6、securitySchemes, 配置安全模式
7、securityContexts() 配置安全上下文
8、 globalResponseMessage() 全局返回信息
示例:.globalResponseMessage(RequestMethod.GET, responseMessageList);
*/
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList<>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContextList = new ArrayList<>();
List<SecurityReference> securityReferenceList = new ArrayList<>();
securityReferenceList.add(new SecurityReference("Authorization", scopes()));
securityContextList.add(SecurityContext
.builder()
.securityReferences(securityReferenceList)
.forPaths(PathSelectors.any())
.build()
);
return securityContextList;
}
private AuthorizationScope[] scopes() {
return new AuthorizationScope[]{new AuthorizationScope("global", "accessAnything")};
}
//全局返回信息
List<ResponseMessage> responseMessageList = new ArrayList<>();
responseMessageList.add(new ResponseMessageBuilder().code(ResultEnum.SUCCESS.getCode()).
message(ResultEnum.SUCCESS.getMessage()).build());
/**
ApiInfo 对象,
1 contact对象:用于配置作者信息,再ApiInfo类中同样提供了Contac类对象的构造
示例:
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("接口文档")
.contact(new Contact("作者姓名", "http://test.lk.cool", "XXXXXx@gmail.com"))
.description("Swagger动态接口文档")
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.version("Demo")
.build();
}
swagger注释注解
Controller类上
@Api(“xxx”):作用在控制层类上
@ApiOperation(“xxx”):作用于方法添加注释
入参出参
单个
@ApiParam(“xxx”):作用于控制层接口参数添加注释
VO类上
@ApiModel(“xxx”):给控制层返回的实体类对象添加注释
@ApiModelProperty(“xxx”):给字段添加注释
默认访问地址
http://localhost:9110/swagger-ui.html