SpringBoot 2.X 版本整合 Swagger + Knife4j 接口文档

省流：请看“三、怎么做接口文档？“的具体实现

一、什么是接口文档？

1.介绍：接口文档是用于说明系统或模块间交互接口详情的说明性文档（即展示接口信息的文档）

2.每条接口包括接口地址、名称、请求类型、请求格式、请求参数、响应参数（含错误）及备注等信息

3.接口文档 = 程序员之间的 “沟通说明书”，里面详细写清楚了不同程序模块之间怎么交互—— 比如要访问哪个网址（接口地址）、用什么方式提交信息（请求类型，比如 GET/POST）、需要提供哪些请求参数和响应参数，以及可能遇到的错误提示，方便大家按照统一规则开发。

4.接口文档由谁提供，供谁使用？

简短：一般是后端或负责人来提供，后端和前端都要使用

专业：接口文档通常由后端开发人员或项目负责人负责编写并提供，其受众主要为参与项目开发的前端和后端开发人员，旨在为双方提供统一的接口信息标准，确保前后端开发协作的高效性与一致性。

二、为什么需要接口文档

• 通过场景引出接口文档的重要性

场景1：某社交 APP 迭代消息推送功能，原后端开发小李离职，新接手的小陈需调试接口。因无接口文档，小陈只能逐行啃代码推断逻辑，耗时费力且易因参数理解偏差导致功能异常。

场景2：某团队开发外卖 APP，前端负责用户下单界面，后端处理订单逻辑。前端需调用后端 “提交订单” 功能时，若没有文档说明请求地址（如/api/order/submit）、参数格式（如订单金额、地址字段）及响应状态码，前后端仅靠口头沟通传递信息，极易造成对接标准模糊导致订单提交失败。

• 接口文档的作用

1.接口文档提供书面内容归档，便于参考查阅、知识沉淀与维护，避免口口相传。

2.接口文档便于前端和后端开发对接，是前后端联调的介质。后端只需提供文档并做简要说明，前端即可依据文档独立开发，无需后端反复解释接口细节，从而大幅降低重复沟通成本，提升联调效率。

3.好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率.

三、怎么做接口文档？

1.手写（比如：腾讯文档、Markdown笔记、语雀）

2.自动化接口文档生成（即自动根据项目代码生成完整的文档或在线调试的网页）
国外：Swagger、Postman(侧重接口管理)
国内：Apifox、Apipost、Eolink

3.具体实现

knife4j官方文档：快速开始 | Knife4j

（1）添加依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

（2）配置yml属性

# 接口文档配置
knife4j:
  enable: true
  openapi:
    title: "接口文档"
    version: 1.0
    group:
      default:
        api-rule: package
        api-rule-resources:
          - com.xxx.controller

注意：com.xxx.controller 改为你的 controller 包路径

（3）访问

文档地址：http://ip:port/doc.html

• ip是本地（即localhost），运行项目后可看到port，比如地址：http://localhost:8080/doc.html

注意：线上环境千万不要把接口地址暴露出去！！！