Java 后端整合 Swagger + Knife4j 接口文档

🕗 发布于 2025-01-16 11:47 java

文章目录

一. 接口文档
二. 后端整合 Swagger + Knife4j

一. 接口文档

1.1 什么是接口文档？

什么是接口文档？写接口信息的文档，每条接口包括：

请求参数
响应参数
- 错误码
接口地址
接口名称
请求类型
请求格式
备注

who 谁用？一般是后端或者负责人来提供，后端和前端都要使用

1.2 为什么需要接口文档？

有个书面内容（背书或者归档），便于大家参考和查阅，便于 沉淀和维护 ，拒绝口口相传
接口文档便于前端和后端开发对接，前后端联调的介质。后端 => 接口文档 <= 前端
好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率

1.3 怎么做接口文档？

手写（比如腾讯文档、Markdown 笔记）
自动化接口文档生成：自动根据项目代码生成完整的文档或在线调试的网页。Swagger，Postman（侧重接口管理）（国外）；apifox、apipost、eolink（国产）

1.4 接口文档有哪些技巧？

Swagger 原理：

引入依赖（Swagger 或 Knife4j：https://doc.xiaominfo.com/knife4j/documentation/get_start.html）
自定义 Swagger 配置类
定义需要生成接口文档的代码位置（Controller）
千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启
启动即可
可以通过在 controller 方法上添加 [@Api、@ApiImplicitParam(name ](/Api、@ApiImplicitParam(name ) = “name”,value = “姓名”,required = true) [@ApiOperation(value ](/ApiOperation(value ) = “向客人问好”) 等注解来自定义生成的接口描述信息

如果 springboot version >= 2.6，需要添加如下配置：

spring:
  mvc:
  pathmatch:
      matching-strategy: ANT_PATH_MATCHER

二. 后端整合 Swagger + Knife4j

2.1 Swagger

2.1.1 引入依赖

      <!-- swagger 接口文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.1.2 设置Swagger配置类

然后是config文件的新建

package ***;

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;

/**
 * 自定义 Swagger 接口文档的配置
 */
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                                //.any() // 扫描全部的接口，默认
                                //.none() // 全部不扫描
                                .basePackage("") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                ).paths(PathSelectors.any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                ).build();
    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact("jin", // 作者姓名
                "", // 作者网址
                "@qq.com"); // 作者邮箱
        return new ApiInfoBuilder().title("123") // 标题
                .description("你若盛开，清风徐来") // 描述
                .termsOfServiceUrl("https://github.com/") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)").licenseUrl("123").contact(contact).build();
    }
}

2.1.3 报错

如果你的springboot版本是大于等于2.4以上，大概率会出现一下报错：

在application.yaml配置文件中添加如下配置：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

2.2 Knife4j

2.2.1 引入依赖

<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <!--使用Swagger2-->
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2.2.2 在config目录（没有就新建）下创建Knife4j配置依赖，代码如下：

添加配置类，注意：basePackage 需要填写 controller 的路径

千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启

package ***;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.EnableSwagger2WebMvc;

/**
 * @author
 * 自定义 Swagger 接口文档的配置
 */

/**
 * @Description: 自定义 Swagger 接口文档的配置
 */
@Configuration
@EnableSwagger2WebMvc
@Profile({"dev", "test"})   //版本控制访问
public class SwaggerConfig {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 这里一定要标注你控制器的位置
                .apis(RequestHandlerSelectors.basePackage(".controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * api 信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("jin")
                .description("jin接口文档")
                .termsOfServiceUrl("https://github.com")
                .contact(new Contact(""))
                .version("1.0")
                .build();
    }
}

2.2.3 版本问题导致的报错

如果你的springboot版本是大于等于2.4以上，大概率会出现一下报错

需要配置，不然会和Swagger一样的报错

mvc:
  pathmatch:
    matching-strategy: ant_path_matcher
profiles:
  active: dev

可以通过在 controller 方法上添加 @Api、@ApiImplicitParam(name = “name”,value = “姓名”,required = true) @ApiOperation(value = “向客人问好”) 等注解来自定义生成的接口描述信息。

千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({“dev”, “test”}) 限定配置仅在部分环境开启

去application.yml中修改默认配置，并在swaggerConfig中加上@Profile注解

（补充一下，一定要注意运行环境和扫描的controller包的路径。）

否则报出异常：

2.2.4 访问地址，注意端口、实际的地址

端口对应，正常访问http://localhost:8080/doc.html

如果配置类当中有配置路径，则需要加上

server:
  port: 8888
  servlet:
    context-path: /api

该地址访问：http://localhost:8888/api/doc.html

原文地址：https://blog.csdn.net/weixin_69912448/article/details/145163688

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！

上一篇：reac 后端接口返回二进制文件流前端导出文件
下一篇：从零开始深度学习：（1）张量的常用操作

vue3 uiapp实现一个数字输入组件，输入非数字会默认转成最小数
用户输入字符串、汉字、字母等非数字，会默认转成最小数使用vue3 最新语法defineModel。
阅读更多2025-01-17
python爬虫笔记
首先，获取网页源码需要模拟浏览器的访问行为对网页进行请求，即使用urllopen打开对应的请求，而请求需要定制一个请求对象，该对象需要统一资源定位器url和请求头headers进行构造，headers
阅读更多2025-01-17
python+openCV+ffmpeg进行物联网设备拉流rtmp
通过物联网网关设备，推流的rtmp视频流，在此基础上完成对视频使用分类集的视频流抽帧（及对帧数计数，达到目标帧时才进行识别降低延迟率）检测，并重新推流为rtsp(和对rtmp处理类似，设置一个合理的f
阅读更多2025-01-17
腾讯会议升级：推出AI小助手Pro、支持对外展示认证身份、组织协同能力增强
1月15日，腾讯会议宣布产品升级，涵盖多个关键功能点。
阅读更多2025-01-17
层次聚类算法：自动发现数据结构及其关键影响因素分析
层次聚类算法通过自动发现数据中的相似组，提供了一种有效的方式来处理无监督学习任务。它的灵活性和多层次分类能力使其在许多领域中具有广泛的应用潜力，尤其是在数据类别不明确或变化频繁的情况下
阅读更多2025-01-17
【C++】面试题整理（未完待续）
最近面试题，感觉有些比较基础的好久不用就记不得了，整理一下。题目的答案是个人整理的不能保证是标准答案。
阅读更多2025-01-17
Redis的哨兵机制
Redis 的主从复制模式下，一旦主节点由于故障不能提供服务，需要人工进行主从切换，同时大量的客户端需要被通知切换到新的主节点上，对于上了⼀定规模的应用来说，这种方案是无法接受的，于是 Redis 从
阅读更多2025-01-17
extends配置项详解
extends配置项详解
阅读更多2025-01-17
Jaeger UI使用、采集应用API排除特定路径
Jaeger使用:版本、Tags、精确匹配、排除匹配；排除特定路径、Filter、tracer.activeSpan().finish()
阅读更多2025-01-17
图像识别opencv翻转
1,0,-1代表不一样的翻转效果。
阅读更多2025-01-17