SpringBoot中整合knife4j接口文档的实践

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 文件

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 所在的包

3、启动类

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();

}

}

我们需要开放其静态资源的访问，启动类实现 WebMvcConfigurer 接口，重写 addResourceHandlers 方法

4、访问文档

启动项目，访问路径http://localhost:8080/doc.html

三、注意

访问时，如果提示 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 是一样的

1、controller

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 = "后台管理端--用户模块")

@ConmFbaytroller

@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，每一个参数的注释

2、实体类

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，字段的注解

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。