Spring Boot 整合 Swagger 接口文档工具

我们在开发接口的时候,会将接口文档给前端的开发者进行对接。我们可以通过 Postman 或者 Yapi 等接口管理工具进行编写管理。实际开发中,接口的管理确实也应该通过专业的工具管理。

那么,如果只是小团队使用,我们是否可以在边开发的过程中,顺便把接口文档给写了呢?

当然,本文,我们就来谈谈怎么在 Spring Boot 整合 Swagger 接口文档工具。

本文开发环境:

  • spring boot 版本 2.1.3.RELEASE
  • java SDK 版本 1.8
  • mac m1 系统

本文,在笔者之前的项目 Spring Security 简单了解使用 基础上开发。

笔者尝试了下整合 swagger3,但是因为原先项目版本的问题,未能整合成功。故整合 swagger2,文档作用都一样,就是页面长得不一样,可以放心使用。

添加依赖

我们在 pom.xml 中添加下面的依赖:

xml 复制代码
<!-- 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>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

并在配置文件中添加配置:

xml 复制代码
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

引入配置

在包 com.launch.config 中添加 SwaggerConfig.java 类:

java 复制代码
package com.launch.config;

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.launch.controller")) // 接口所在的包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Launch 系统") // 标题
                .description("Jimmy Control System") // 描述
                .version("1.0.0") // 版本
                // 姓名,联系 link,邮箱
                .contact(new Contact("Jimmy", "https://juejin.cn/user/1996368846261294", "reng99@outlook.com"))
                .build();
    }

}

到此,我们运行项目,打开连接 http://localhost:8080/swagger-ui/index.html,咦,404 耶~

处理 404

版本的问题,使得我们无法读取 swagger 包下面的页面。那么,我们来重写。

我们在 com.launch.config 中新增 WebMvcConfig.java 文件:

java 复制代码
package com.launch.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;


@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

    }
}

重新启动,访问路径 http://localhost:8080/doc.html,就可以看到效果。

在本文 Spring Security 简单了解使用 中,我们已经开发好了六个接口。点击进入其中一个,比如 queryAll 查询所有用户的接口,可看到其文档:

我们还可以对该接口进行调试:

感兴趣的读者可以自行尝试。

参考

相关推荐
Data_Adventure几秒前
Vue 3 手机外观组件库
前端·github copilot
sunbin2 分钟前
windows 环境下编译kestra并启动
后端
泯泷6 分钟前
Tiptap 深度教程(二):构建你的第一个编辑器
前端·架构·typescript
野犬寒鸦6 分钟前
Pipeline功能实现Redis批处理(项目批量查询点赞情况的应用)
java·服务器·数据库·redis·后端·缓存
屁__啦12 分钟前
前端错误-null结构
前端
lichenyang45312 分钟前
从0开始的中后台管理系统-5(userList动态展示以及上传图片和弹出创建用户表单)
前端
꧁༺摩༒西༻꧂13 分钟前
Spring Boot Actuator 监控功能的简介及禁用
java·数据库·spring boot
jzy371113 分钟前
京东开源王炸!JoyAgent-JDGenie 通用智能体一键部署指南,DeepSeek 大模型完美适配
后端·openai·ai编程
未来之窗软件服务17 分钟前
解析 div 禁止换行与滚动条组合-CSS运用
前端·css
Java中文社群37 分钟前
快看!百度提前批的面试难度,你能拿下吗?
java·后端·面试