水生的网络日志 水生的网络日志
首页
  • 前言
  • Java核心
  • 企业级开发
  • 数据库
  • 计算机基础
  • 求职面试
  • 技术文档
  • GitHub技巧
  • Nodejs
  • 博客搭建
  • 技术文档
  • GitHub技巧
  • Nodejs
  • 博客搭建
  • 分类
  • 标签
  • 归档
关于
GitHub (opens new window)

水生

记录我的所思、所学、所想
首页
  • 前言
  • Java核心
  • 企业级开发
  • 数据库
  • 计算机基础
  • 求职面试
  • 技术文档
  • GitHub技巧
  • Nodejs
  • 博客搭建
  • 技术文档
  • GitHub技巧
  • Nodejs
  • 博客搭建
  • 分类
  • 标签
  • 归档
关于
GitHub (opens new window)
  • 前言

  • Java核心

  • 企业级开发

    • Spring Boot开发

      • 创建Maven父子项目
      • Spring Boot整合MyBatis
      • Spring Boot整合Swagger
        • 1、Swagger介绍
          • Swagger
          • Swagger-UI
          • 常用注解
        • 2、整合Swagger
          • 添加项目依赖
          • 添加Swagger的配置
        • 3、Swagger接口注解
        • 4、启动项目测试Swagger
        • 5、Swagger小结
      • Spring Boot整合Redis实现缓存验证码
      • Spring Boot整合Spring Sercurity和JWT
      • Spring Boot整合Spring Task实现定时任务
      • Spring Boot整合ElasticSearch实现商品搜索
      • Spring Boot整合MongoDB实现文档操作
      • Spring Boot整合RabbitMQ实现延迟消息
    • Spring Cloud开发

  • 数据库

  • 计算机基础

  • 求职面试

  • 知识库
  • 企业级开发
  • Spring Boot开发
水生
2019-12-11
目录

Spring Boot整合Swagger

本文当主要是在[[02【开源学习-架构篇】Spring Boot整合MyBatis]]的基础上实现,主要是对在线API框架SwaggerUI的整合。

# 1、Swagger介绍

# Swagger

Swagger是一种接口描述语言,用于描述使用JSON表示的RESTful API。

Swagger与一组开源软件工具一起使用,以设计,构建,记录和使用RESTful Web服务。

通常配合Swagger-UI使用,方便程序员在线联调接口和自动生成接口说明文档。

# Swagger-UI

Swagger-UI是HTML, Javascript, CSS的一个集合,可以动态地根据注解生成在线API文档。

# 常用注解

  • @Api:用于修饰Controller类,生成Controller相关文档信息
  • @ApiOperation:用于修饰Controller类中的方法,生成接口方法相关文档信息
  • @ApiParam:用于修饰接口中的参数,生成接口参数相关文档信息
  • @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息

# 2、整合Swagger

# 添加项目依赖

在pom.xml中新增Swagger-UI相关依赖

<!--Swagger-UI API文档生产工具-->
		<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>
1
2
3
4
5
6
7
8
9
10
11

# 添加Swagger的配置

添加Swagger-UI的Java配置文件

注意:Swagger对生成API文档的范围有三种不同的选择

  • 生成指定包下面的类的API文档
  • 生成有指定注解的类的API文档
  • 生成有指定注解的方法的API文档

Swagger2Config配置类:

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("mall")
                .contact("sds")
                .version("1.0")
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 3、Swagger接口注解

给原有的品牌管理Controller添加上Swagger注解

@Api(tags = "PmsBrandController", description = "商品品牌管理")
@RestController
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;

    private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);


    @ApiOperation("用于获取所有品牌")
    @GetMapping("listAll")
    public CommonResult<List<PmsBrand>> getBrandList() {
        return CommonResult.success(brandService.listAllBrand());
    }

    @ApiOperation("添加品牌")
    @PostMapping("addBrand")
    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
        CommonResult commonResult;
        int count = brandService.createBrand(pmsBrand);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrand);
            LOGGER.debug("createBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("createBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }

    @ApiOperation("更新指定id品牌信息")
    @PostMapping("/update/{id}")
    public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
        CommonResult commonResult;
        int count = brandService.updateBrand(id, pmsBrandDto);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrandDto);
            LOGGER.debug("updateBrand success:{}", pmsBrandDto);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
        }
        return commonResult;
    }

    @ApiOperation("删除指定id的品牌")
    @DeleteMapping("/delete/{id}")
    public CommonResult deleteBrand(@PathVariable("id") Long id) {
        int count = brandService.deleteBrand(id);
        if (count == 1) {
            LOGGER.debug("deleteBrand success :id={}", id);
            return CommonResult.success(null);
        } else {
            LOGGER.debug("deleteBrand failed :id={}", id);
            return CommonResult.failed("操作失败");
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# 4、启动项目测试Swagger

  • 打开Swagger-UI接口接口管理界面

输入测试地址:http://localhost:8082/swagger-ui.html#/

image-20211212171704648

  • 测试接口

image-20211212171841169

# 5、Swagger小结

优点:

  • 作为一款开源工具、免费
  • 能够可视化API设计
  • 能够帮助团队确定API设计风格,并且辅助团队开发工作
  • 能够进行接口的在线联调测试
  • 能够直接生成API文档,省去编写API文档的时间

不足:

  • 侵入性比较大,需要与服务端代码集成,直接嵌入到工程代码 (opens new window)中;
  • 将文档参数和应用参数杂糅在一起,不易阅读。
  • 比较依赖于项目, 无法独立部署,项目挂掉,文档也无法访问,增加后期维护难度。
  • 提示功能差劲,很多时候在编辑预览中没问题,导出来部署就显示不正常,而且不支持多人编辑,只能一次一个人改,部署相当不方便。
  • 用户体验无论请求还是响应无法方便的输入自定义JSON格式,特别是多层嵌套 (opens new window),异常繁琐。
  • 界面UI做的不是很美观易用。

因此,针对这些问题,又有了Swagger和Yapi的组合,[[【开源学习-架构优化】整合SwaggerUI + Yapi]]],更加简便了的官方starter请查看[[【开源学习-架构优化】整合Swagger官方Stater]]

思维导图:

image-20211223214919667

编辑 (opens new window)
#Spring Boot#Swagger
上次更新: 2022/11/26, 22:18:38
Spring Boot整合MyBatis
Spring Boot整合Redis实现缓存验证码

← Spring Boot整合MyBatis Spring Boot整合Redis实现缓存验证码→

最近更新
01
基于微服务案例的Maven实战
05-08
02
使用Seata彻底解决Spring Cloud中的分布式事务问题
11-26
03
Spring Boot整合RabbitMQ实现延迟消息
11-26
更多文章>
Theme by Vdoing | Copyright © 2019-2022 水生 | MIT License
  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式