SpringBoot从入门到精通(二十二)使用Swagger2优雅构建 RESTful API文档-阿里云开发者社区

开发者社区> 章为忠学架构> 正文

SpringBoot从入门到精通(二十二)使用Swagger2优雅构建 RESTful API文档

简介: 在实际项目中,Api 接口系统对接过程中,Api 接口文档是非常重要的文档。一般是设计完成之后,同时编写Api 接口文档,然后将接口文档发给相关人员,于是大家就按照该文档开发、集成并最终上线。但是,这是一种非常理想的状态,实际开发中,接口不断变化,接口文档也必须保持更新,这是一个非常麻烦的过程!为了解决这些问题,Swagger2 应运而生。接下来,就和大伙聊一聊 Spring Boot 如何整合Swagger2,使用Swagger2构建 RESTful API文档。
+关注继续查看

前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制。

在实际项目中,Api 接口系统对接过程中,Api 接口文档是非常重要的文档。一般是设计完成之后,同时编写Api 接口文档,然后将接口文档发给相关人员,于是大家就按照该文档开发、集成并最终上线。但是,这是一种非常理想的状态,实际开发中,接口不断变化,接口文档也必须保持更新,这是一个非常麻烦的过程!为了解决这些问题,Swagger2 应运而生。接下来,就和大伙聊一聊 Spring Boot 如何整合Swagger2,使用Swagger2构建 RESTful API文档。

 

一、什么是Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是世界上最流行的 API 表达工具 。我们知道,RESTful API 可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web前端开发等。为了减少与其他团队平时开发期间的频繁沟通成本,一般我们会创建一份API文档来记录所有接口细节,但是api 接口文档存在以下问题:

  • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),要创建这样一份高质量的文档本身就是件非常吃力的事。
  • 随着需求的不断变化,接口文档也必须同步修改,这很容易导致文档和业务不一致情况出现。

为了解决这些问题,Swagger2 应运而生。它可以轻松的整合到Spring Boot 中,自动生成强大的 RESTful API文档。这样既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了完整的测试页面,来调试每个API 接口。

下面就以SpringBoot中集成Swagger为例做介绍说明Swagger2 的功能和作用。

 

二、Spring Boot 集成Swagger 2

Spring Boot 集成 Swagger 2很简单,首先新建一个 SpringBoot 项目,这里就不重新创建项目,直接使用之前的rest 测试项目。然后引入依赖并做基础配置即可:

1、配置Swagger2的依赖

在pom.xml 配置文件中,增加Swagger 2 的相关依赖,具体如下:

<!-- swagger2 依赖配置-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

注意,swagger 2 的版本号和 spring boot的版本号有些不匹配,最开始用2.2的版本和spring boot 的版本还不匹配,后来把 swagger 2 换成了2.8。

 

2、创建Swagger 2配置类

在com.weiz.config 包中,增加Swagger 2 的配置类,SwaggerConfig 类,具体代码如下:

package com.weiz.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weiz.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("Spring Boot相关文章请关注:https://www.cnblogs.com/zhangweizhong")
                .termsOfServiceUrl("https://www.cnblogs.com/zhangweizhong")
                .contact("架构师精进")
                .version("1.0")
                .build();
    }
    /**
     *  swagger增加url映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

说明:@Configuration 注解让Spring boot来加载该类配置,@EnableSwagger2注解启用Swagger 2,通过配置一个Docket Bean,配置映射路径和要扫描的接口的位置。apiInfo,主要配置一下Swagger2文档网站的信息,例如网站的title、网站的描述、使用的协议等等。

注意

  1、basePackage 可以在SwaggerConfig 里面配置 com.weiz.controller,也可以在启动器里面 ComponentScan 配置。

  2、需要在swaggerconfig 中配置swagger 的url 映射。

 

三、添加文档说明

上面配置完成之后,接下来需要在api 接口上增加内容说明。这里方便起见,就直接在之前的UserController 中,增加相应的接口内容说明,代码如下所示:

package com.weiz.controller;
import com.weiz.pojo.SysUser;
import com.weiz.service.UserService;
import com.weiz.utils.JSONResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.n3r.idworker.Sid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Api(tags = {"用户接口"})
@RestController
@RequestMapping("/")
public class UserController {
    @Autowired
    private UserService userService;
    @Autowired
    private Sid sid;
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @PostMapping(value = "user")
    public JSONResult create(@RequestBody SysUser user) throws Exception {
        String userId = sid.nextShort();
        user.setId(userId);
        userService.saveUser(user);
        return JSONResult.ok("保存成功");
    }
    @ApiOperation(value="更新用户详细信息", notes="根据id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
    @PutMapping(value = "user")
    public JSONResult update(@RequestBody SysUser user) {
        userService.updateUser(user);
        return JSONResult.ok("保存成功");
    }
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @DeleteMapping("user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        userService.deleteUser(userId);
        return JSONResult.ok("删除成功");
    }
    @ApiOperation(value="查询用户",notes = "通过用户ID获取用户信息")
    @GetMapping("user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        return JSONResult.ok(userService.queryUserById(userId));
    }
}

说明:

  1、@Api注解,用来给整个controller 增加说明。

  2、@ApiOperation注解,用来给各个API 方法增加说明。

  3、@ApiImplicitParams、@ApiImplicitParam注解,用来给参数增加说明。

  4、Swagger 还有用于对象参数的注解,对象参数的描述也可以放在实体类中。这里不细说,大家可以自行研究。

 

四、测试验证

完成上面的配置和代码修改之后,Swagger 2 就集成到Spring boot 项目中了,接下来启动Spring Boot程序,访问:http://localhost:8088/swagger-ui.html

image.png

 

最后

以上,就把Spring Boot 如何整合Swagger2,使用Swagger2构建 RESTful API文档 介绍完了。实现还是比较简单的,但是还是需要理解里面的相关注解的用法。

这个系列课程的完整源码,也会提供给大家。大家关注我的微信公众号(架构师精进),回复:springboot源码。获取这个系列课程的完整源码。



推荐阅读:

SpringBoot从入门到精通(二十一)如何优雅的设计 RESTful API 接口版本号,实现 API 版本控制!

SpringBoot从入门到精通(二十)快速构建RESTful Web API 服务

SpringBoot从入门到精通(十九)使用注解实现动态Sql、参数传递

SpringBoot从入门到精通(十八)Mybatis系列之——使用注解的方式实现后台管理功能

SpringBoot从入门到精通(十七)MyBatis系列之——创建自定义mapper 实现多表关联查询!

SpringBoot从小白到精通(十六)使用pagehelper实现分页查询功能

SpringBoot从小白到精通(十五)实现开发环境热部署

SpringBoot从小白到精通(十四)使用JdbcTemplate操作数据库,配置多数据源!

SpringBoot从小白到精通(十三)如何实现事务保存

SpringBoot从小白到精通(十二)logback日志配置

SpringBoot从小白到精通(十一)统一异常处理

SpringBoot从小白到精通(十)使用Interceptor拦截器,一学就会!

SpringBoot从小白到精通(九)使用@Async实现异步执行任务

SpringBoot从小白到精通(八)熟悉@EnableScheduling,一秒搞定定时任务

SpringBoot从小白到精通(七)使用Redis实现高速缓存架构

SpringBoot从小白到精通(六)使用Mybatis实现增删改查【附详细步骤】

SpringBoot从小白到精通(五)Thymeleaf的语法及常用标签

SpringBoot从小白到精通(四)Thymeleaf页面模板引擎

SpringBoot从小白到精通(三)系统配置及自定义配置

SpringBoot从小白到精通(二)如何返回统一的数据格式

SpringBoot从小白到精通(一)如何快速创建SpringBoot项目

 

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
1分钟构建API网关日志解决方案
访问日志(Acccess Log)是由web服务生成的日志,每一次api请求都对应一条访问记录,内容包括调用者IP、请求的URL、响应延迟、返回状态码、请求和响应字节数等重要信息。 阿里云API网关提供API托管服务,在微服务聚合、前后端分离、系统集成上为用户便利的产品。
7845 0
SpringBoot实战(三)之使用RestFul Web服务
一、导入maven依赖 4.0.0 org.springframework gs-consuming-rest 0.1.0 org.springframework.
1252 0
如何让接口文档自动生成,SpringBoot中Swagger的使用
在开发过程中,java后端需要与客户端进行交互,需要将后端的接口及参数写成文档给调用者查阅。一个问题也有此而生,需求改动频繁,接口设计也会随之改动,文档修改的不及时会带来很大的问题。 Swagger是一个自动生成文档的工具,可以在线查阅文档,减少了开发人员的负担,下面我们就来看看如何在SpringBoot中使用Swagger。
941 0
SpringBoot2.0 整合 Swagger2 ,构建接口管理界面
一、Swagger2简介 1、Swagger2优点 整合到Spring Boot中,构建强大RESTful API文档。省去接口文档管理工作,修改代码,自动更新,Swagger2也提供了强大的页面测试功能来调试RESTful API。
2290 0
JavaScript进阶【二】JavaScript 严格模式(use strict)的使用
版权声明:本文为博主原创文章,未经博主允许不得转载。更多学习资料请访问我爱科技论坛:www.52tech.tech https://blog.csdn.net/m0_37981569/article/details/79249309 ...
777 0
阿里云产品部总经理:AIoT 加速企业构建数字世界-APSARA 2019
分享人介绍:何云飞 阿里云智能产品管理部总经理、AIoT事业部产品与解决方案总经理
4133 0
+关注
章为忠学架构
获取源码、资料,请关注我的微信公众号(架构师精进)
67
文章
2
问答
文章排行榜
最热
最新
相关电子书
更多
文娱运维技术
立即下载
《SaaS模式云原生数据仓库应用场景实践》
立即下载
《看见新力量:二》电子书
立即下载