SpringBoot中整合knife4j接口文档的实践
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护
接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护
一、界面先赏
1、首页
2、接口文档
3、调试
二、整合knife4j
1、引入maven依赖
com.github.xiaoymin knife4j-spring-boot-starter 2.0.2 com.google.guava guava 29.0-jre
一般情况我们只需要引入knife4j的依赖即可，但是有时会出现guava的版本冲突，所以，我们把guava一起引入进来
2、knife4j配置文件
创建Knife4jConfig文件
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.builders.ApiInfoBuilder;
importspringfox.documentation.builders.PathSelectors;
importspringfox.documentation.builders.RequestHandlerSelectors;
importspringfox.documentation.service.ApiInfo;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spring.web.plugins.Docket;
importspringfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*knife4j配置
*
*@AuthorLizhou
*/
@Configuration
@EnableSwagger2
publicclassKnife4jConfig{
@Bean
publicDocketcreateRestApi(){
returnnewDocket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.zyxx"))
.paths(PathSelectors.any())
.build();
}
privateApiInfoapiInfo(){
returnnewApiInfoBuilder()
.title("SpringBoot项目后台服务API接口文档")
.description("使用knife4j搭建的后台服务API接口文档")
.termsOfServiceUrl("http://localhost:8080/")
.contact("lizhou")
.version("1.0.0")
.build();
}
}
整体配置与Swagger2几乎一致，扫描controller所在的包
3、启动类
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.builders.ApiInfoBuilder;
importspringfox.documentation.builders.PathSelectors;
importspringfox.documentation.builders.RequestHandlerSelectors;
importspringfox.documentation.service.ApiInfo;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spring.web.plugins.Docket;
importspringfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*knife4j配置
*
*@AuthorLizhou
*/
@Configuration
@EnableSwagger2
publicclassKnife4jConfig{
@Bean
publicDocketcreateRestApi(){
returnnewDocket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.zyxx"))
.paths(PathSelectors.any())
.build();
}
privateApiInfoapiInfo(){
returnnewApiInfoBuilder()
.title("SpringBoot项目后台服务API接口文档")
.description("使用knife4j搭建的后台服务API接口文档")
.termsOfServiceUrl("http://localhost:8080/")
.contact("lizhou")
.version("1.0.0")
.build();
}
}
我们需要开放其静态资源的访问，启动类实现WebMvcConfigurer接口，重写addResourceHandlers方法
4、访问文档
启动项目，访问路径http://localhost:8080/doc.html
三、注意
访问时，如果提示knife4j文档异常，检查下自己的拦截器是否没有放开knife4j所需要的请求
需要在拦截器，放开请求
packagecom.zyxx.common.config;
importorg.springframework.beans.factory.annotation.Autowired;
importorg.springframework.context.annotation.Configuration;
importorg.springframework.web.servlet.config.annotation.InterceptorRegistration;
importorg.springframework.web.servlet.config.annotation.InterceptorRegistry;
importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;
importjava.util.ArrayList;
importjava.util.List;
/**
*注册拦截器
*
*@AuthorLizhou
**/
@Configuration
publicclassWebConfigurerimplementsWebMvcConfigurer{
@Autowired
privateLoginInterceptorloginHandlerInterceptor;
@Override
publicvoidaddInterceptors(InterceptorRegistryregistry){
InterceptorRegistrationir=registry.addInterceptor(loginHandlerInterceptor);
//拦截路径
ir.addPathPatterns("/*");
//不拦截路径
Listirs=newArrayList();
irs.add("/login");
irs.add("/api/*");
//开放knife4j
irs.add("/doc.html");
irs.add("/service-worker.js");
irs.add("/swagger-resources");
ir.excludePathPatterns(irs);
}
}
四、使用
使用注解的方式与swagger2是一样的
1、controller
importcom.zyxx.common.utils.ResponseResult; importcom.zyxx.sbm.service.MgtUserService; importio.swagger.annotations.Api; importio.swagger.annotations.ApiImplicitParam; importio.swagger.annotations.ApiImplicitParams; importio.swagger.annotations.ApiOperation; importorg.springframework.beans.factory.annotation.Autowired; importorg.springframework.stereotype.Controller; importorg.springframework.web.bind.annotation.GetMapping; importorg.springframework.web.bind.annotation.RequestMapping; importorg.springframework.web.bind.annotation.ResponseBody; /** **用户信息表前端控制器 *
* *@authorlizhou *@since2020-06-30 */ @Api(tags="后台管理端--用户模块") @Controller @RequestMapping("/mgt-user") publicclassMgtUserController{ @Autowired privateMgtUserServicemgtUserService; @ApiOperation(value="分页查询用户数据",notes="分页查询用户数据") @ApiImplicitParams({ @ApiImplicitParam(name="page",value="页码数",required=true), @ApiImplicitParam(name="limit",value="每页条数",required=true) }) @GetMapping("list") @ResponseBody publicResponseResultlistUser(intpage,intlimit){ returnmgtUserService.listUser(page,limit); } }
@Api，整个类的注释
@ApiOperation，方法上的注释
@ApiImplicitParams，参数列表的注释
@ApiImplicitParam，每一个参数的注释
2、实体类
importcom.baomidou.mybatisplus.annotation.IdType; importcom.baomidou.mybatisplus.extension.activerecord.Model; importcom.baomidou.mybatisplus.annotation.TableId; importjava.io.Serializable; importio.swagger.annotations.ApiModel; importio.swagger.annotations.ApiModelProperty; importlombok.Data; importlombok.EqualsAndHashCode; importlombok.experimental.Accessors; /** **用户信息表 *
* *@authorlizhou *@since2020-06-30 */ @Data @EqualsAndHashCode(callSuper=false) @Accessors(chain=true) @ApiModel(value="mgt_user对象",description="用户信息对象") publicclassMgtUserextendsModel{ privatestaticfinallongserialVersionUID=1L; @TableId(value="id",type=IdType.AUTO) @ApiModelProperty(value="主键ID") privateLongid; @ApiModelProperty(value="姓名") privateStringname; @ApiModelProperty(value="年龄") privateIntegerage; @ApiModelProperty(value="技能") privateStringskill; @ApiModelProperty(value="评价") privateStringevaluate; @ApiModelProperty(value="分数") privateLongfraction; @Override protectedSerializablepkVal(){ returnthis.id; } }
@ApiModel，实体类的注解
@ApiModelProperty，字段的注解
到此这篇关于SpringBoot中整合knife4j接口文档的实践的文章就介绍到这了,更多相关SpringBoot整合knife4j内容请搜索毛票票以前的文章或继续浏览下面的相关文章希望大家以后多多支持毛票票！
声明：本文内容来源于网络，版权归原作者所有，内容由互联网用户自发贡献自行上传，本网站不拥有所有权，未作人工编辑处理，也不承担相关法律责任。如果您发现有涉嫌版权的内容，欢迎发送邮件至：czq8825#qq.com（发邮件时，请将#更换为@）进行举报，并提供相关证据，一经查实，本站将立刻删除涉嫌侵权内容。