在前后台开发时,需要将接口信息封装成接口文档,可选用knife4j框架生成API接口文档。
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!其底层是对Springfox的封装,使用方式也和Springfox一致,只是对接口文档UI进行了优化。
为了避免重复开发,可将该功能抽离成一个通用的功能,可自定义一个Knife4j-spring-boot-starter,在实际运用时,引用该starter的坐标即可。
如何自定义一个starter,可参考我的上一篇文章Springboot Starter介绍以及实现自定义Starter
2 定义SwaggerProperties4.0.0 org.springframework.boot spring-boot-starter-parent 2.2.2.RELEASE com.starter swagger-spring-boot-starter 1.0 org.springframework.boot spring-boot-starter org.springframework.boot spring-boot-autoconfigure com.github.xiaoymin knife4j-spring-boot-starter 2.0.1 org.projectlombok lombok
@Data
@ConfigurationProperties(prefix = "swagger2")
public class SwaggerProperties {
private boolean enabled = false;
Map dockets = new HashMap<>();
}
@Data
class SwaggerInnerProperties {
//api info properties;
private String group;
private String title;
private String description;
private String version;
//Contact联系人设置
private ContactInfo ContactInfo=new ContactInfo();
private String basePackage;
private List baseUrls = new ArrayList<>();
private List excludePaths = new ArrayList<>();
private ListglobaleParams=new ArrayList<>();
}
@Data
class ContactInfo {
private String name;
private String url;
private String email;
}
@Data
class GlobaleParamsConfig {
private String name;
private String description;
private String type;
private boolean required=false;
}
3 定义SwaggerAutoConfiguration
@EnableSwagger2
@Configuration
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnProperty(name = "enabled",prefix = "swagger2",havingValue = "true")
public class SwaggerAutoConfiguration implements BeanFactoryAware {
private Logger logger= LoggerFactory.getLogger(this.getClass());
@Autowired
private SwaggerProperties properties;
private BeanFactory beanFactory;
@Override
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
this.beanFactory=beanFactory;
}
public SwaggerAutoConfiguration(SwaggerProperties properties) {
this.properties = properties;
}
@Bean
public List createDockets(SwaggerProperties properties){
ConfigurableBeanFactory configurableBeanFactory =
(ConfigurableBeanFactory) beanFactory;
List docketList=new ArrayList<>();
if(properties.getDockets()!=null&&properties.getDockets().size()>0){
//遍历创建Docket文档
if(properties.getDockets().isEmpty()){
logger.error("docket配置信息错误");
}else{
//遍历创建Docket文档
for(String group:properties.getDockets().keySet()){
SwaggerInnerProperties innerProperties=properties.dockets.get(group);
Docket docket=createOneDocket(innerProperties);
//bean工厂创建Bean
configurableBeanFactory.registerSingleton(group, docket);
docketList.add(docket);
}
}
}
return docketList;
}
public Docket createOneDocket(SwaggerInnerProperties innerProperties){
Docket docket=new Docket(DocumentationType.SWAGGER_2);
docket.groupName(innerProperties.getGroup());
//配置Api Info
docket.apiInfo(createApiInfo(innerProperties));
//设置请求路径
docket.select().apis(RequestHandlerSelectors.basePackage(innerProperties.getBasePackage()));
// base-path处理
// 当没有配置任何path的时候,解析
public ApiInfo createApiInfo(SwaggerInnerProperties innerProperties){
ApiInfo apiInfo=new ApiInfoBuilder()
.version(innerProperties.getVersion())
.title(innerProperties.getTitle())
.description(innerProperties.getDescription())
.contact(new Contact(innerProperties.getContactInfo().getName(),innerProperties.getContactInfo().getUrl(),innerProperties.getContactInfo().getEmail()))
.build();
return apiInfo;
}
public ListsetParametes(ListglobaleParams){
ListparameterList=new ArrayList<>();
for(GlobaleParamsConfig config:globaleParams){
ParameterBuilder parameterBuilder = new ParameterBuilder();
// header query cookie形式的
parameterBuilder.name(config.getName()).description(config.getDescription()).modelRef(new ModelRef(config.getType())).parameterType("header").required(config.isRequired());
Parameter build = parameterBuilder.build();
parameterList.add(build);
}
return parameterList;
}
}
4 配置spring.factories
项目结构如下
在类路径下META-INF 新建spring.factories文件。
org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.config.SwaggerAutoConfiguration5 测试
新建项目,引入依赖
com.starter swagger-spring-boot-starter 1.0
配置
#SwaggerProperties
swagger2:
enabled: true
dockets:
test:
group: test
title: test-title
description: test-description
version: version1
ContactInfo:
name: lyf
url: lyf-url
email: lyf-email
basePackage: com.foxconn.assetmanagement.test
tes1:
group: test1
title: test1-title
description: test1-description
version: version2
ContactInfo:
name: lyf
url: lyf-url
email: lyf-email
basePackage: com.foxconn.assetmanagement.test1
项目路径如下
项目启动后输入localhost:8080/doc.html



