Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

简介: Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

1. 引言

各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不一致。 程序员的特点是特别不喜欢写文档,但是又同时特别不喜欢别人不写文档。所以 API 文档工具这时就应运而生了,本篇文章我们将会介绍 API 文档工具 Swagger2 。

2. 快速上手

既然 Swagger2 是一个 API 文档工具,我们就在代码中看一下这个文档工具在 Spring Boot 中是如何使用的吧。

2.1 引入依赖

代码清单:spring-boot-swagger/pom.xml

***

<!-- swagger工具包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

这里选用的版本是 2.9.2 ,同时也是目前最新的一个版本。

2.2 配置类 SwaggerConfig

代码清单:spring-boot-swagger/src/main/ java/com/springboot/springbootswagger/config/SwaggerConfig.java ***

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.show}")
    private boolean swaggerShow;
 
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerShow)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.springbootswagger"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2 演示接口RESTful APIs")
                .version("1.0")
                .build();
    }
}

由于 Swagger 是一个 API 文档工具,我们肯定不能在生产环境中开启,所以笔者这里在配置中增加了 swagger.show ,在不同环境的配置文件中配置不同的值,或者如果有配置中心,这个配置可以添加到配置中心中,笔者这里示例简单起见就添加在 application 配置文件中了。这样,我们就可以优雅的开启或者关闭 Swagger 的功能。

2.3 实体类

代码清单:spring-boot-swagger/src/main/java/com/springboot/springbootswagger/model/User.java

***

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户演示类", description = "请求参数类")
public class User {
    @ApiModelProperty(example = "1", notes = "用户ID")
    private Long id;
    @ApiModelProperty(example = "geekdigging", notes = "用户名")
    private String nickName;
    @ApiModelProperty(example = "1570689455000", notes = "创建时间")
    private Date createDate;
    @ApiModelProperty(example = "18", notes = "用户年龄")
    private Integer age;
}

Swagger 注解详细说明:

API 作用范围 使用位置
@ApiModel 描述返回对象的意义 用在返回对象类上
@ApiModelProperty 对象属性 用在出入参数对象的字段上
@Api 协议集描述 用于 controller 类上
@ApiOperation 协议描述 用在 controller 的方法上
@ApiResponses Response集 用在 controller 的方法上
@ApiResponse Response 用在 @ApiResponses 里边
@ApiImplicitParams 非对象参数集 用在 controller 的方法上
@ApiImplicitParam 非对象参数描述 用在 @ApiImplicitParams 的方法里边

2.4 Controller

代码清单:spring-boot-swagger/src/main/java/com/springboot/springbootswagger/controller/UserController.java

***

@Api(value = "用户管理演示")
@RestController
public class UserController {
 
    @Autowired
    UserService userService;
 
    @GetMapping("/getUserById/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据用户 id 获取用户信息", tags = "查询用户信息类")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
 
    @GetMapping("/getAllUsers")
    @ApiOperation(value = "获取全部用户信息", notes = "获取全部用户信息", tags = "查询用户信息类")
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }
 
    @PostMapping("/saveUser")
    @ApiOperation(value = "新增/修改用户信息")
    public User saveUser(@RequestBody User user) {
        return userService.saveUser(user);
    }
 
    @DeleteMapping("/deleteById")
    @ApiOperation(value = "删除用户信息", notes = "根据用户 id 删除用户信息")
    public String deleteById(@PathVariable Long id) {
        userService.deleteById(id);
        return "success";
    }
}
  • @ApiOperation 中的 tag 标签可用于接口分组

2.5 展示结果如下

启动工程,打开浏览器访问: http://localhost:8080/swagger-ui.html ,可以看到如下页面:

这张图中可以看到我们的 tag 分组。

3. 示例代码

示例代码-Github

示例代码-Gitee

4. 参考

https://blog.csdn.net/xupeng874395012/article/details/68946676

目录
打赏
0
1
1
0
122
分享
相关文章
1天消化完Spring全家桶文档!DevDocs:一键深度解析开发文档,自动发现子URL并建立图谱
DevDocs是一款基于智能爬虫技术的开源工具,支持1-5层深度网站结构解析,能将技术文档处理时间从数周缩短至几小时,并提供Markdown/JSON格式输出与AI工具无缝集成。
105 1
1天消化完Spring全家桶文档!DevDocs:一键深度解析开发文档,自动发现子URL并建立图谱
|
2月前
|
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
81 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
2月前
|
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
93 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的 maven 依赖
在项目中使用Swagger2工具时,需导入Maven依赖。尽管官方最高版本为2.8.0,但其展示效果不够理想且稳定性欠佳。实际开发中常用2.2.2版本,因其稳定且界面友好。以下是围绕2.2.2版本的Maven依赖配置,包括`springfox-swagger2`和`springfox-swagger-ui`两个模块。
53 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档—— Swagger 简介
第6课介绍了在Spring Boot中集成Swagger2以展示在线接口文档的方法。随着前后端分离架构的发展,API文档成为连接前端与后端开发的重要纽带。然而,代码更新频繁导致文档难以同步维护,Swagger2解决了这一问题。通过Swagger,在线API文档不仅方便了接口调用方查看和测试,还支持开发者实时测试接口数据。本文使用Swagger 2.2.2版本,讲解如何在Spring Boot项目中导入并配置Swagger2工具,从而高效管理接口文档。
114 0
Spring AI与DeepSeek实战四:系统API调用
在AI应用开发中,工具调用是增强大模型能力的核心技术,通过让模型与外部API或工具交互,可实现实时信息检索(如天气查询、新闻获取)、系统操作(如创建任务、发送邮件)等功能;本文结合Spring AI与大模型,演示如何通过Tool Calling实现系统API调用,同时处理多轮对话中的会话记忆。
338 57
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
博客不应该只有代码和解决方案,重点应该在于给出解决方案的同时分享思维模式,只有思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
如何使用非结构化 API 高效处理文档
手动处理非结构化文档面临格式不一致、数据噪声多和信息检索困难等挑战,导致低效率和合规风险。Unstructured API 通过自动化文档处理,利用AI技术简化分类、归类和异常检测,节省时间和提高准确性。Supametas.AI 作为领先平台,支持多种文件类型(如文本、图片、视频),适用于各行各业,可与Salesforce、Zendesk等工具无缝集成,确保数据流动顺畅并提升工作效率。其强大的功能包括数据摄取、处理技术、检索增强生成、灵活性、可扩展性和集成能力,帮助企业和小公司高效处理大量非结构化数据,实现业务增长和优化工作流程。
161 4
通义灵码 API 开发文档自动生成场景DEMO
通义灵码API开发文档自动生成场景DEMO展示了通过自定义指令,大模型能快速根据类代码生成Markdown格式的API文档。文档详细描述API的入参、出参,并可生成测试代码等示例,帮助开发者快速创建美观的API文档。
236 1

热门文章

最新文章

AI助理

你好,我是AI助理

可以解答问题、推荐解决方案等