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

在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护

接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看、维护

一、界面先赏

1、首页

2、接口文档

3、调试

二、整合 knife4j

1、引入 maven 依赖

<!-- knife4j接口文档 start -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.2</version>
</dependency>
<!-- 避免版本冲突 -->
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>29.0-jre</version>
</dependency>

一般情况我们只需要引入 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<String> irs = new ArrayList<String>();
    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;

/**
 * <p>
 * 用户信息表 前端控制器
 * </p>
 *
 * @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,每一个参数的注释

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;

/**
 * <p>
 * 用户信息表
 * </p>
 *
 * @author lizhou
 * @since 2020-06-30
 */
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="mgt_user对象", description="用户信息对象")
public class MgtUser extends Model<MgtUser> {

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

到此这篇关于SpringBoot中整合knife4j接口文档的实践的文章就介绍到这了,更多相关SpringBoot整合knife4j内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • Springboot2整合knife4j过程解析

    knife4j官网:https://doc.xiaominfo.com/guide/useful.html 这玩艺就swagger的升级版,但是用起来比swagger方便多了,至少不会出现莫名的版本兼容问题 下面记录一个配置示例 1.代码结构 2.pom.xml <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0&

  • SpringBoot使用knife4j进行在线接口调试

    前言 我们在开发一个Java Web的项目,如果项目整体采用前后端分离的架构的方式,我们会经常使用Swagger来进行接口调试和为前端提供接口文档,但是Swagger并没有实际上那么方便,比如我们在发送Post请求时,参数选填还是非常不友好,那么有没有更好的工具呢? 正文 knife4j knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,具有小巧,轻量,并且功能强悍的优点. Knife4j提供两大核心功能:文档说

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

    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看.维护 一.界面先赏 1.首页 2.接口文档 3.调试 二.整合 knife4j 1.引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> <group

  • Springboot中整合knife4j接口文档的过程详解

    目录 什么是knife4j 界面欣赏 主页 接口文档 调试界面 参数实体 整合 knife4j 引入 maven 依赖 knife4j 配置文件 配置API接口 knife4j 常用特性 全局参数 离线文档 在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发. 什么是knife4j 简单说knife4j就swagger的升级版API文档的一个框架,但是用起来比swagger方便多了,UI更加丰富. 界面欣赏

  • Spring Boot项目集成Knife4j接口文档的实例代码

    目录 1.在pom.xml引入依赖包 2.创建Knife4j配置文件 3.使用Knife4j注解 4.全局参数 Knife4j就相当于是swagger的升级版,对于我来说,它比swagger要好用得多 1.在pom.xml引入依赖包 <!-- Swagger配置依赖knife4j --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-b

  • SpringBoot集成Swagger2生成接口文档的方法示例

    我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等.它还是和API消费方沟通的重要工具.在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档.个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义.而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API.我们今天就来看下 Swagger2 与 SpringBoot 的结合. 准备工作

  • SpringBoot使用swagger生成api接口文档的方法详解

    目录 前言 具体例子 maven配置 项目application.yml配置 springApplication添加swagger注解 在控制层添加swagger注解 前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot系列文章: spring boot项目使用mybatis-plus代码生成实例 具体例子 maven配置 在使用之前,我们需要添加s

  • Spring Cloud Gateway 整合 knife4j 聚合接口文档功能

    当系统中微服务数量越来越多时,如果任由这些服务散落在各处,那么最终管理每个项目的接口文档将是一件十分麻烦的事情,单是记住所有微服务的接口文档访问地址就是一件苦差事了.当如果能够将所有微服务项目的接口文档都统一汇总在同一个可视化页面,那么将大大减少我们的接口文档管理维护工作,为此,我们可以基于 Spring Cloud Gateway 网关 + nacos + knife4j 对所有微服务项目的接口文档进行聚合,从而实现我们想要的文档管理功能 注:本案例需要 springboot 提前整合 nac

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

  • Java开发SpringBoot集成接口文档实现示例

    目录 swagger vs smart-doc Swagger的代码侵入性比较强 原生swagger不支持接口的参数分组 简单罗列一下smart-doc的优点 SpringBoot集成 smart-doc 引入依赖,版本选择最新版本 新建配置文件smart-doc.json 通过执行maven 命令生成对应的接口文档 访问接口文档 功能增强 1. 开启调试 2. 通用响应体 3. 自定义Header 4. 参数分组 5. idea配置doc 6. 完整配置 小结 之前我在SpringBoot老鸟

随机推荐