当前位置:

首页 > 编程开发 > SpringBoot整合Knife4j实现接口文档自动生成的最佳实践

SpringBoot整合Knife4j实现接口文档自动生成的最佳实践

写接口文档有多烦人?做过前后端联调的朋友都懂。手写吧,费时费力还容易跟代码对不上号;不写吧,前端同事跑来问接口参数,一天能打断你八回。Knife4j 这玩意儿就是来终结这种痛苦的——只要加几个注解,接口文档自动生成,还附带在线调试功能。 一、为什么选 Knife4j 目前市面上做接口文档的方案不少,

本文目录

    写接口文档有多烦人?做过前后端联调的朋友都懂。手写吧,费时费力还容易跟代码对不上号;不写吧,前端同事跑来问接口参数,一天能打断你八回。Knife4j 这玩意儿就是来终结这种痛苦的——只要加几个注解,接口文档自动生成,还附带在线调试功能。

    SpringBoot整合Knife4j实现接口文档自动生成的最佳实践

    一、为什么选 Knife4j

    目前市面上做接口文档的方案不少,但从实际体验来看,Knife4j 对国内开发者确实很友好。核心优势在于两点:一是 UI 界面做了汉化,看着舒服;二是它不仅仅是文档展示工具,在线调试功能体验比原生的 Swagger UI 更流畅。

    拿它和 Swagger UI、手写文档对比一下,差别就很直观了:Knife4j 的支持度更完善,Swagger UI 虽然也能在线调试,但界面是英文的,手写文档就更不用说了,维护成本高到离谱。代码上,Knife4j 和 Swagger 都是走注解方式,侵入性很低,但 Knife4j 的维护成本几乎为零——因为文档跟代码是自动同步的。

    二、集成 Knife4j

    1. 引入依赖

    将下面这个依赖加到 pom.xml 里,版本号建议用稳定版:

    
        com.github.xiaoymin
        knife4j-spring-boot-starter
        3.0.3
    

    2. 配置

    然后在 application.yml 或 application.properties 里补充这几项配置,确保 Spring 的路径匹配方式兼容 Knife4j:

    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher
    knife4j:
      enable: true
      setting:
        language: zh-CN
        enable-swagger-models: true
        enable-document-manage: true
        swagger-model-order: 1

    3. 配置类

    创建一个配置类,注册一个 Docket Bean。这里的关键是指定好你想扫描的控制器包路径,比如下面这个例子扫的是 com.zhang 包下的所有控制器:

    @Configuration
    @EnableKnife4j
    public class Knife4jConfig {
    
        @Bean
        public Docket defaultApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhang"))
                .paths(PathSelectors.any())
                .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                .title("秒杀系统接口文档")
                .description("电商秒杀系统 RESTful API")
                .version("V1.0")
                .contact(new Contact("张政", "", ""))
                .build();
        }
    }
    

    做完上面这三步,项目启动后访问 http://localhost:9090/doc.html,就能看到自动生成的接口文档页面了。页面里不光能看到每个接口的请求方式、参数说明、返回示例,还能直接点「调试」按钮在线测试接口,省去了来回切换工具的痛苦。

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    centosnginxssl配置最佳实践
    centosnginxssl配置最佳实践

    CentOS系统下,通过SSL(安全套接字层)加密技术,可保障Nginx传输数据的安全性。那么,如何配置Nginx以使用SSL呢?以下是一些最佳实践:获取SSL证书:你可以从Let’s Encrypt免费获取SSL证书,或者购买一个商业证书。使用Certbot工具可以自动化证书的申请和续订过程。安装

    MongoDBLinux配置中的最佳实践有哪些
    MongoDBLinux配置中的最佳实践有哪些

    在Linux系统上如何优化MongoDB配置一 系统层优化使用XFS 或 ext4文件系统,生产环境更推荐XFS(高并发与元数据性能更好);挂载数据盘时启用noatime/nodiratime减少元数据写入;SSD 建议设置较小的readahead(如32),机械盘可适当增大;避免使用NFS存放数据

    LinuxJS日志存储最佳实践
    LinuxJS日志存储最佳实践

    在Linux系统下,若要通过Ja vaScript(Node.js)进行日志存储,有以下一些最佳实践可供参考,这些实践能够保障日志得到有效管理与分析:选择合适的日志库:使用流行的日志库,如winston、pino或bunyan,这些库提供了丰富的功能,包括日志级别、格式化、传输和存储。设置日志级别:

    DebianOracle存储配置最佳实践
    DebianOracle存储配置最佳实践

    在Debian上部署Oracle存储,该如何选择架构?又要如何取舍?优先采用 Oracle ASM 管理数据库存储,按功能划分为两个磁盘组:一个用于 DATA(数据文件、控制文件、在线重做日志等,关键业务可用 HIGH REDUNDANCY 三路镜像),另一个用于 FRA(快速恢复区:归档日志、RM

    Kubernetes生产环境最佳实践
    Kubernetes生产环境最佳实践

    众所周知,Kubernetes很难! 以下是在生产中使用它应遵循的一些最佳实践。遵循这些步骤能够确保更高的安全性和生产效率。毫无疑问,DevOps已经走过了一段很长的路! 借助于Kubernetes编排平台使得公司比以往更快地发布软件。随着容器用于构建和发布软件的使用量不断增加,Kubernetes

    高德最佳实践:Serverless规模化落地有哪些价值?
    高德最佳实践:Serverless规模化落地有哪些价值?

    导读:曾经看上去很美、一直被观望的 Serverless,现已逐渐进入落地的阶段。今年的"十一出行节",高德在核心业务规模化落地 Serverless,由 Serverless 支撑的业务在流量高峰期的表现十分优秀。传统应用也能带来同样的体验,那么 Serverless 的差异化价值又是什么呢?本文

    面试|不可不知的十大Hive调优技巧最佳实践
    面试|不可不知的十大Hive调优技巧最佳实践

    Apache Hive作为一款构建于Apache Hadoop之上的数据仓库软件项目,其作用是实现数据的查询与分析。它在Hadoop的HDFS中充当SQL接口,能够通过类似SQL的接口,对存储于与Hadoop集成的各类数据库及文件系统中的数据进行查询。可以说,对于从事数据开发工作的人员而言,无论是日

    OpenTelemetry在服务网格架构下的最佳实践
    OpenTelemetry在服务网格架构下的最佳实践

    【百度云原生导读】OpenTelemetry 由著名的 OpenTracing、 OpenCensus 两个产品在 2019 年合并而来,拥有广泛的应用场景和强大的开发团队。2021年,OpenTelemetry 的使用成为新的行业规范,通过在各个数据源之间建立一致性,使得数据收集以及处理更加便捷。

    orc软件使用技巧与最佳实践分享
    orc软件使用技巧与最佳实践分享

    OCR软件通过图像预处理、字符识别和后处理将图片文字转为可编辑文本。选择时需关注识别准确率、版面处理及输出格式。预处理可提升质量,识别时应正确设置语言与模式,并善用区域选择。后处理包括校对形近字和整理格式,建立标准化流程与注意数据安全可提高效率。

    C++11实现缓存线程池最佳实践
    C++11实现缓存线程池最佳实践

    一、线程池概述 1.1 线程池概念 线程池技术其实很简单,就是系统里预先准备好一些线程,等任务来了,直接从池子里分配一个去处理。任务处理完了,线程不销毁,而是还回去,继续服务下一个任务。这样一来,创建和销毁线程的开销就被大大降低了。 线程池的特点: 线程复用:相当于把线程当成一次性餐具变成了可重复使

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。