Swagger 接口文档生成工具

最新推荐文章于 2025-11-06 09:58:19 发布

原创最新推荐文章于 2025-11-06 09:58:19 发布 · 366 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#Swagger

IDEA-Java各开发环境安装和常见问题解决专栏收录该内容

33 篇文章

订阅专栏

本文介绍了Swagger在企业开发中的优势，重点讲解了如何使用Knife4j（SwaggerUI增强工具）进行接口文档生成和配置，包括依赖导入、API信息设置和静态资源映射。同时，对比了Swagger和Yapi在不同阶段的角色，强调了接口注解的重要性和改进之处。

Swagger

Swagger
- Swagger优点介绍
Knife4j （SwaggerUI 的增强工具）

Swagger

Swagger优点介绍

Swagger 在目前企业中作为前后端开发对接的技术已经得到了非常广泛的应用:

后端开发人员只需要根据 OpenAPI 官方定义的注解就可以把接口文档非常丰富的呈现给前端接口对接人员。
接口文档是随着代码的变动实时更新，
提供了在线 HTML 文档辅助开发人员可以进行接口联调测试，

大大省去了技术人员写文档的烦恼，也提升了企业开发的效率，减少沟通成本。
官网：https://swagger.io/

Knife4j （SwaggerUI 的增强工具）

Knife4j 是一个 SwaggerUI 的增强工具，同时也提供了一些增强功能，使用 Java+Vue 进行开发，帮助开发者能在编写接口注释时更加完善.

knife4j官网：https://doc.xiaominfo.com/knife4j/

Knife4j使用

依赖导入

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

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
</dependency>

导入knife4j配置

在sky-server模块的WebMvcConfig复制以下代码

// 通过knife4j生成接口文档
@Bean
public Docket docket() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("苍穹外卖-管理后台")
        .version("2.0")
        .description("管理后台接口文档")
        .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
        .groupName("管理端接口")
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.sky.web.admin"))
        .paths(PathSelectors.any())
        .build();
    return docket;
}

// 通过knife4j生成接口文档
@Bean
public Docket docket2() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("苍穹外卖-小程序端")
        .version("1.0")
        .description("小程序端接口文档")
        .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
        .groupName("小程序端接口")
        .apiInfo(apiInfo)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.sky.web.app"))
        .paths(PathSelectors.any())
        .build();
    return docket;
}

设置静态资源映射

由于Swagger生成的在线文档中，涉及到很多静态资源，这些静态资源需要添加静态资源映射，否则接口文档页面无法访问。

在这里插入图片描述

因此需要在 WebMvcConfig类中的addResourceHandlers方法中增加如下配置

// 设置静态资源映射
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}