在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护
接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护
界面先赏
首页
接口文档
调试
整合knife4j
引入maven依赖
com.github.xiaoymin
knife4j-spring-boot-starter
2.0.2
com.google.guava
guava
29.0-jre
一般情况我们只需要引入knife4j的依赖即可，但是有时会出现guava的版本冲突，我们把guava一起引入进来
knife4j配置文件
创建Knife4jConfig文件
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* knife4j 配置
*
* @Author Lizhou
*/
@Configuration
@EnableSwagger2
public class Knife4jConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage('com.zyxx'))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title('SpringBoot项目 后台服务API接口文档')
.description('使用 knife4j 搭建的后台服务API接口文档')
.termsOfServiceUrl('http://localhost:8080/')
.contact('lizhou')
.version('1.0.0')
.build();
}
}
整体配置与Swagger2几乎一致，扫描controller所在的包
启动类
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.spring.web.SpringfoxWebMvcConfiguration;
@SpringBootApplication
@ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
public class SbmApplication implements WebMvcConfigurer {
public static void main(String[] args) {
SpringApplication.run(SbmApplication.class, args);
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler('doc.html').addResourceLocations('classpath:/META-INF/resources/');
registry.addResourceHandler('/webjars/**').addResourceLocations('classpath:/META-INF/resources/webjars/');
}
}
我们需要开放其静态资源的访问，启动类实现WebMvcConfigurer接口，重写addResourceHandlers方法
访问文档
启动项目，访问路径
注意
访问时，如果提示knife4j文档异常，检查下自己的拦截器是否没有放开knife4j所需要的请求需要在拦截器，放开请求
package com.zyxx.common.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.util.ArrayList;
import java.util.List;
/**
* 注册拦截器
*
* @Author Lizhou
**/
@Configuration
public class WebConfigurer implements WebMvcConfigurer {
@Autowired
private LoginInterceptor loginHandlerInterceptor;
@Override
public void addInterceptors(InterceptorRegistry registry) {
InterceptorRegistration ir = registry.addInterceptor(loginHandlerInterceptor);
// 拦截路径
ir.addPathPatterns('/*');
// 不拦截路径
List irs = new ArrayList();
irs.add('/login');
irs.add('/api/*');
// 开放knife4j
irs.add('/doc.html');
irs.add('/service-worker.js');
irs.add('/swagger-resources');
ir.excludePathPatterns(irs);
}
}
使用
使用注解的方式与swagger2是一样的
import com.zyxx.common.utils.ResponseResult;
import com.zyxx.sbm.service.MgtUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
/**
*
* 用户信息表 前端控制器
*
*
* @author lizhou
* @since 2020-06-30
*/
@Api(tags = '后台管理端--用户模块')
@Controller
@RequestMapping('/mgt-user')
public class MgtUserController {
@Autowired
private MgtUserService mgtUserService;
@ApiOperation(value = '分页查询用户数据', notes = '分页查询用户数据')
@ApiImplicitParams({
@ApiImplicitParam(name = 'page', value = '页码数', required = true),
@ApiImplicitParam(name = 'limit', value = '每页条数', required = true)
})
@GetMapping('list')
@ResponseBody
public ResponseResult listUser(int page, int limit) {
return mgtUserService.listUser(page, limit);
}
}
@Api，整个类的注释@ApiOperation，方法上的注释@ApiImplicitParams，参数列表的注释@ApiImplicitParam，每一个参数的注释
实体类
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.extension.activerecord.Model;
import com.baomidou.mybatisplus.annotation.TableId;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;
/**
*
* 用户信息表
*
*
* @author lizhou
* @since 2020-06-30
*/
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value='mgt_user对象', description='用户信息对象')
public class MgtUser extends Model {
private static final long serialVersionUID = 1L;
@TableId(value = 'id', type = IdType.AUTO)
@ApiModelProperty(value = '主键ID')
private Long id;
@ApiModelProperty(value = '姓名')
private String name;
@ApiModelProperty(value = '年龄')
private Integer age;
@ApiModelProperty(value = '技能')
private String skill;
@ApiModelProperty(value = '评价')
private String evaluate;
@ApiModelProperty(value = '分数')
private Long fraction;
@Override
protected Serializable pkVal() {
return this.id;
}
}
@ApiModel，实体类的注解@ApiModelProperty，字段的注解
分组展示
我们针对多个包内的API接口，可以选择分组展示，配置如下：
package com.asurplus.common.knife4j;
import com.asurplus.common.consts.SystemConst;
import org.springframework.beans.factory.annotation.Value;
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;
/**
* swagger2 配置
*
* @Author Lizhou
*/
@Configuration
@EnableSwagger2
public class Knife4jConfig {
/**
* 是否开启swagger
*/
@Value('${knife4j.enabled}')
private boolean enabled;
@Bean('appApi')
public Docket appApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否开启
.enable(enabled)
// 分组名称
.groupName('APP端API文档')
.apiInfo(apiInfo())
.select()
// 扫描包位置，扫描所有带有此注解的方法
.apis(RequestHandlerSelectors.basePackage('com.asurplus.api'))
.paths(PathSelectors.any())
.build();
}
@Bean('adminApi')
public Docket adminApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否开启
.enable(enabled)
// 分组名称
.groupName('管理端API文档')
.apiInfo(apiInfo())
.select()
// 扫描包位置，扫描所有带有此注解的方法
.apis(RequestHandlerSelectors.basePackage('com.asurplus.system'))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title(SystemConst.SYSTEM_ITEM_NAME + '管理后台服务API接口文档')
// 简介
.description('使用 knife4j 搭建的后台服务API在线接口文档')
// 服务条款url
.termsOfServiceUrl('无')
// 版本
.version('1.0.0')
// 作者
.contact(new Contact('Administrators', '无', '无'))
// 构建
.build();
}
}
其中.enable()表示开启还是不开启，当我们线上环境的时候，需要关闭在线文档，增加系统安全性
以上就是，SpringBoot中整合knife4j接口文档的全部过程
文章为作者独立观点，不代表股票交易接口观点
相关文章
股民评论