配置:
- 引入jar包(由于先使用2.7.0导致类的说明无法显示具体问题有待大家一起探讨,现改为使用2.6.0版本,)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.0</version>
</dependency>
- 引入spring java配置
package com.ak1ak1.config;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.List;
import static com.google.common.base.Predicates.or;
import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.PathSelectors.regex;
@Configuration // 配置注解,自动在本类上下文加载一些环境变量信息
@EnableSwagger2 // 使swagger2生效
@EnableWebMvc
//@ComponentScan(basePackages = {"com.ak1ak1.controller.v1"}) //需要扫描的包路径
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket swaggerSpringMvcPlugin() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("APi文档")
.select() // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.basePackage("com.ak1ak1.controller.v1"))//需要扫描的包路径
.paths(paths())
//.apis(RequestHandlerSelectors.any()) // 对所有api进行监控
//.paths(PathSelectors.any()) // 对所有路径进行监控
.build()
// .securitySchemes(securitySchemes())
// .securityContexts(securityContexts())
;
}
private Predicate<String> paths() {
return PathSelectors.any();
//return or(regex("/person.*"));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("APi文档")
.description("此APi文档接口调用")
//.license("License Version 2.0")
//.licenseUrl("http://blog.csdn.net/yangshijin1988")
.version("2.0").build();
}
//--------------------------------------------------------------------------------------------------------------------------------------------
private List<ApiKey> securitySchemes() {
return newArrayList(
new ApiKey("clientId", "客户端ID", "header"),
new ApiKey("clientSecret", "客户端秘钥", "header"),
new ApiKey("accessToken", "客户端访问标识", "header"));
}
private List<SecurityContext> securityContexts() {
return newArrayList(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/*.*"))
.build()
);
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return newArrayList(
new SecurityReference("clientId", authorizationScopes),
new SecurityReference("clientSecret", authorizationScopes),
new SecurityReference("accessToken", authorizationScopes));
}
}
使用
-
启动项目服务后访问地址: http://127.0.0.1:8084/swagger-ui.html#/(注:服务器地址加项目端口);
-
类注解说明:
@Api(description=“广告推荐”, tags={“advertisement”},value=“advertisement”)
2.1:说明()
tags–表示说明不能填写中文,需要中文请用 description
value–也是说明,可以使用tags替代 但是tags如果有多个值,会生成多个lis
2.2案例
Java控制层类
Swagger页面显示情况
- 方法注解说明: @ApiOperation(httpMethod = “POST”, value = “个人信息”)
3.1说明
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用)
(注意事项:若方法名开头含add,get,del,up的字眼的情况请给方法设置该方法的请求方式httpMethod)
3.2案例
Swagger页面显示
- 字段注解说明:
4.1方式1:在方法上添加注解使用
Swagger页面显示
4.2方式二:在方法里:
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填
或者
或者
- 实体类注解说明
@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏