文档章节

SpringBoot | 第十章:Swagger2的集成和使用

oKong
 oKong
发布于 07/22 00:33
字数 1496
阅读 287
收藏 15

前言

前一章节介绍了mybatisPlus的集成和简单使用,本章节开始接着上一章节的用户表,进行Swagger2的集成。现在都奉行前后端分离开发和微服务大行其道,分微服务及前后端分离后,前后端开发的沟通成本就增加了。所以一款强大的RESTful API文档就至关重要了。而目前在后端领域,基本上是Swagger的天下了。

Swagger2介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。

swagger首页

SpringBoot集成

这里选用的swagger版本为:2.8.0

0.pom依赖

    <!--swagger -->
    <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> 

1.编写配置文件(Swagger2Config.java)

主要是添加注解@EnableSwagger2和定义Docket的bean类。

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    //是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用-demo示例")
                .description("oKong | 趔趄的猿")
                // 作者信息
                .contact(new Contact("oKong", "https://blog.lqdev.cn/", "499452441@qq.com"))
                .version("1.0.0")
                .build();
    }
}

3.添加文档内容(一般上是在Controller,请求参数上进行注解,这里以上章节的UserController进行配置)

UserController

/**
 * 用户控制层 简单演示增删改查及分页
 * 新增了swagger文档内容 2018-07-21
 * @author oKong
 *
 */
@RestController
@RequestMapping("/user")
@Api(tags="用户API")
public class UserController {

    @Autowired
    IUserService userService;
    
    @PostMapping("add")
    @ApiOperation(value="用户新增")
    //正常业务时, 需要在user类里面进行事务控制,控制层一般不进行业务控制的。
    //@Transactional(rollbackFor = Exception.class)
    public Map<String,String> addUser(@Valid @RequestBody UserReq userReq){
        
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        //由于设置了主键策略 id可不用赋值 会自动生成
        //user.setId(0L);
        userService.insert(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "新增成功");
        //事务测试
        //System.out.println(1/0);
        return result;
    }
    
    @PostMapping("update")
    @ApiOperation(value="用户修改")    
    public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){
        
        if(userReq.getId() == null || "".equals(userReq.getId())) {
            throw new CommonException("0000", "更新时ID不能为空");
        }
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        user.setId(Long.parseLong(userReq.getId()));        
        userService.updateById(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "更新成功");
        return result;
    }
    
    @GetMapping("/get/{id}")
    @ApiOperation(value="用户查询(ID)")    
    @ApiImplicitParam(name="id",value="查询ID",required=true)
    public Map<String,Object> getUser(@PathVariable("id") String id){
        //查询
        User user = userService.selectById(id);
        if(user == null) {
            throw new CommonException("0001", "用户ID:" + id + ",未找到");
        }
        UserResp resp = UserResp.builder()
                .id(user.getId().toString())
                .code(user.getCode())
                .name(user.getName())
                .status(user.getStatus())
                .build();
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", resp);
        return result;
    }
    
    @GetMapping("/page")
    @ApiOperation(value="用户查询(分页)")        
    public Map<String,Object> pageUser(int current, int size){
        //分页
        Page<User> page = new Page<>(current, size);
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", userService.selectPage(page));
        return result;
    }
        
}

UserReq.java

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {
    
    @ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
    String id;
    
    @ApiModelProperty(value="编码",dataType="String",name="code",example="001")
    @NotBlank(message = "编码不能为空")
    String code;
    
    @ApiModelProperty(value="名称",dataType="String",name="name",example="oKong")
    @NotBlank(message = "名称不能为空")
    String name;
}

Swagger访问与使用

api首页路径:http://127.0.0.1:8080/swagger-ui.html

**调试:**点击需要访问的api列表,点击try it out!按钮,即可弹出一下页面:

Try it out!

执行:

Execute

结果:

结果

大家可下载示例,查看自定义的字符出现的位置,这样可以对其有个大致了解,各字段的作用领域是哪里。

Swagger常用属性说明

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

常用的注解@Api@ApiOperation@ApiModel@ApiModelProperty示例中有进行标注,对于其他注解,大家可自动谷歌,毕竟常用的就这几个了。有了swagger之后,原本一些post请求需要postman这样的调试工具来进行发起,而现在直接在页面上就可以进行调试了,是不是很爽!对于服务的调用者而已,有了这份api文档也是一目了然,不需要和后端多少沟通成本,按着api说明进行前端开发即可。

总结

本章节主要是对Swagger的集成和简单使用进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。一些比如前端根据swaggerapi-docs进行前端的快速开发,这就需要实际情况实际约定了,比如快速的生成表单页等也是很方便的事情。最后,强烈建议在生产环境关闭swagger,避免不必要的漏洞暴露!

最后

目前互联网上很多大佬都有SpringBoot系列教程,如有雷同,请多多包涵了。本文是作者在电脑前一字一句敲的,每一步都是实践的。若文中有所错误之处,还望提出,谢谢。

老生常谈

  • 个人QQ:499452441
  • 微信公众号:lqdevOps

公众号

个人博客:https://blog.lqdev.cn

完整示例:chapter-10

© 著作权归作者所有

共有 人打赏支持
oKong
粉丝 462
博文 55
码字总数 127990
作品 0
福州
高级程序员
Spring Boot 全家桶 - SpringBootBucket

Spring Boot 现在已经成为Java 开发领域的一颗璀璨明珠,它本身是包容万象的,可以跟各种技术集成。 本项目对目前Web开发中常用的各个技术,通过和SpringBoot的集成,并且对各种技术通过“一...

一刀
03/05
0
1
恒宇少年/spring-boot-chapter

简书整套文档以及源码解析 专题 专题名称 专题描述 001 Spring Boot 核心技术 讲解SpringBoot一些企业级层面的核心组件 002 Spring Cloud 核心技术 对Spring Cloud核心技术全面讲解 003 Quer...

恒宇少年
04/19
0
0
白话SpringCloud | 第十一章:路由网关(Zuul):利用swagger2聚合API文档

前言 通过之前的两篇文章,可以简单的搭建一个路由网关了。而我们知道,现在都奉行开发,前后端开发的沟通成本就增加了,所以一般上我们都是通过进行api文档生成的。现在由于使用了统一路由网...

oKong
前天
0
0
SpringBoot集成swagger2

springboot-swagger2-demo 项目介绍 SpringBoot集成swagger2 使用说明 引入maven依赖 启用swagger2 在Controller上添加注释信息(非必须) 启动访问 swagger常用注解 案例 demo地址:https://...

晨猫
10/04
0
0
SpringMVC集成springfox-swagger2构建restful API

在集成springfox-swagger2之前,我也尝试着集成了swagger-springmvc,方式差不多,但是swagger-springmvc相对麻烦一点,因为要把它的静态文件copy到自己的项目中。所以还是用新版本的。 至于...

u014231523
2017/01/13
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Shiro | 实现权限验证完整版

写在前面的话 提及权限,就会想到安全,是一个十分棘手的话题。这里只是作为学校Shiro的一个记录,而不是,权限就应该这样设计之类的。 Shiro框架 1、Shiro是基于Apache开源的强大灵活的开源...

冯文议
今天
1
0
linux 系统的运行级别

运行级别 运行级别 | 含义 0 关机 1 单用户模式,可以想象为windows 的安全模式,主要用于修复系统 2 不完全的命令模式,不含NFS服务 3 完全的命令行模式,就是标准的字符界面 4 系统保留 5 ...

Linux学习笔记
今天
2
0
学习设计模式——命令模式

任何模式的出现,都是为了解决一些特定的场景的耦合问题,以达到对修改封闭,对扩展开放的效果。命令模式也不例外: 命令模式是为了解决命令的请求者和命令的实现者之间的耦合关系。 解决了这...

江左煤郎
今天
3
0
字典树收集(非线程安全,后续做线程安全改进)

将500W个单词放进一个数据结构进行存储,然后进行快速比对,判断一个单词是不是这个500W单词之中的;来了一个单词前缀,给出500w个单词中有多少个单词是该前缀. 1、这个需求首先需要设计好数据结...

算法之名
昨天
15
0
GRASP设计模式

此文参考了这篇博客,建议读者阅读原文。 面向对象(Object-Oriented,OO)是当下软件开发的主流方法。在OO分析与设计中,我们首先从问题领域中抽象出领域模型,在领域模型中以适当的粒度归纳...

克虏伯
昨天
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部