本人是springboot集成swagger2的环境。
并且项目中过滤器会对请求进行拦截,因此需要对一下URI放行:
注意:
生产环境是不允许查看swagger的,可以使用@Profile({“dev”, “test”})
详细禁用方式查看:
https://blog.csdn.net/LiuKingJia/article/details/89878320
// swagger 相关接口
String[] includeUrlSwagger = new String[]{"/webjars", "/v2", "/swagger-resources", "/swagger-ui"};
String uri = request.getRequestURI();
for (String swaggerUrl: includeUrlSwagger) {
if (uri.contains(swaggerUrl)) {
isNeedFilter = false;
break;
}
}
if (!needFilter) {
//不需要过滤直接传给下一个过滤器
filterChain.doFilter(requestWrapper != null ? requestWrapper : request, servletResponse);
}
步骤简要
-
pom导入
-
swagger配置类
-
controller:
类名上:@Api(description = “系统用户相关接口”)
方法上:@ApiOperation(“系统注册登录接口”) -
入参DTO实体类 以及成员变量中的实体类:
类名上:@ApiModel(value = “系统用户”)
变量上:@ApiModelProperty(value = “*审核状态”, example = “2”, allowableValues = “2, 3”, required = true) -
Result实体类 及出参VO实体类:
类名上:@ApiModel(“响应结果”)
变量上:@ApiModelProperty(value = "接口返回状态码; ", example = “1”, position = 0)
**
注意事项
**
-
接口的出参入参尽量使用实体类对象,不要使用Map
-
返回的Result一定要标记泛型,否则生成的接口文档data是空对象,
如:
public Result submitLogin(UserDTO UserDTO) {} -
入参实体类中@ApiModelProperty的required :true或flase时,暂未发现UI界面此配置的展示,因 此在value配置中标明,如:
@ApiModelProperty(value = “*人员ID(修改时必填)”, example = “10086”, required = false, position = 1)
@ApiModelProperty(value = “*年份”, example = “2016”, required = true, position = 1) -
入参字段描述也在value配置中标明
@ApiModelProperty(value = “接口返回状态码;1成功;-1失败;-2参数异常”, example = “1”, position = 0) -
Swagger-UI界面接口参数默认按开头字母排序,如有需求配置position
1.pom依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
2.swagger2配置类
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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Description: swagger 配置
*/
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {
/**
* 创建Rest Api描述
* @return
*/
@Bean
public Docket createRestApi() {
List<ResponseMessage> responseMessageList = new ArrayList<>();
responseMessageList.add(new ResponseMessageBuilder().code(401).message("未经授权")
.responseModel(new ModelRef("Result")).build());
responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源")
.responseModel(new ModelRef("Result")).build());
responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误")
.responseModel(new ModelRef("Result")).build());
return new Docket(DocumentationType.SWAGGER_2)
.globalResponseMessage(RequestMethod.GET, responseMessageList)
.globalResponseMessage(RequestMethod.POST, responseMessageList)
.globalResponseMessage(RequestMethod.PUT, responseMessageList)
.globalResponseMessage(RequestMethod.DELETE, responseMessageList)
.apiInfo(apiInfo())
.select() //按条件指定生成文档接口
.paths(PathSelectors.any())
.build();
}
/**
* 接口描述
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXX项目")
.description("XXXX模块")
.version("1.0")
.build();
}
}
3.注解配置
@Api(description = “管理接口”) :作用在类上面,说命名该controller的作用
@ApiOperation(“添加用户接口”) :作用在方法(具体的接口)上,说明该方法是干什么的接口
POST请求:
@Data
@ApiModel(value = "系统用户", description = "系统用户对象")
public class UserDTO implements Serializable {
// 用户id
@ApiModelProperty(
value = "用户id",
name = "id",
example = "3b8f975f932d98a3582d9c629db9",
required = true)
@NotNull(message = "用户id为空")
private String id;
}
有参GET请求:
/**
* 根据系统模块查询角色列表
*
* @param subSystem
* @return
*/
@GetMapping("list/{subSystem}")
@ApiOperation("根据系统模块查询角色列表")
public Result getRoleListBySystem(
@ApiParam(
value = "系统模块",
allowableValues = "1, 2, 3",
example = "1",
required = true)
@PathVariable("subSystem") String subSystem) {
}
Swagger 通过注解定制接口对外展示的信息,这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型:
• @Api:修饰整个类,描述Controller的作用
• @ApiOperation:描述一个类的一个方法,或者说一个接口
• @ApiParam:单个参数描述
• @ApiModel:用对象来接收参数
• @ApiProperty:用对象接收参数时,描述对象的一个字段
• @ApiResponse:HTTP响应其中1个描述
• @ApiResponses:HTTP响应整体描述
• @ApiIgnore:使用该注解忽略这个API
• @ApiError :发生错误返回的信息
• @ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
• @ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表