点击上方“芋道源码”,选择“置顶公众号”
技术文章第一时间送达!
源码精品专栏
精尽 Dubbo 原理与源码 69 篇
精尽 Netty 原理与源码 61 篇
来源:http://t.cn/EwMgr3F
文档工具导入依赖属性配置实体类restful 风格接口主函数测试总结说点什么
SpringBoot
是为了简化Spring
应用的创建、运行、调试、部署等一系列问题而诞生的产物,自动装配的特性让我们可以更好的关注业务本身而不是外部的XML配置,我们只需遵循规范,引入相关的依赖就可以轻易的搭建出一个 WEB 工程
随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。
前端和后端唯一联系,变成了API接口;API文档自然就成了前后端开发人员联系的纽带,变得尤为的重要,swagger
就是一款让你更好的书写API文档的框架。
文档工具
没有API文档工具之前,基本都是手写API文档的,如有在Word
上写的,有在对应的项目目录下readme.md
上写的,每个公司都有每个公司的玩法,无所谓好坏。但是这种手写文档带来的弊端就是维护起来苦不堪言,对于接口容易发生变化的开发者来说,维护文档就是噩梦….
好在现如今市场上书写API文档的工具有很多,常见的有 postman、yapi、阿里的RAP 但是能称之为框架的,估计也只有swagger
了。
swagger
优缺点
集成方便,功能强大
在线调试与文档生成
代码耦合,需要注解支持,但不影响程序性能
导入依赖
在 pom.xml
中添加 swagger-spring-boot-starter
的依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.battcn</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.4.5-RELEASE</version>
</dependency>
属性配置
配置spring.swagger.enabled
开启swagger
的使用,如果在生产环境中不想用可以在对应的profile
下面将它设置为spring.swagger.enabled=false
,这样一来接口就不存在暴露的风险
# 扫描的包路径,默认扫描所有
spring.swagger.base-package=com.battcn
# 默认为 true
spring.swagger.enabled=true
实体类
swagger
提供了非常齐全的注解,为POJO
提供了@ApiModel
、@ApiModelProperty
,以便更好的渲染最终结果
package com.battcn.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
/**
* @author Levin
* @since 2018/5/10 0007
*/
@ApiModel
public class User implements Serializable {
private static final long serialVersionUID = 8655851615465363473L;
private Long id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
// TODO 省略get set
}
restful 风格接口
注解描述
@Api: 描述
Controller
@ApiIgnore: 忽略该
Controller
,指不对当前类做扫描@ApiOperation: 描述
Controller
类中的method
接口@ApiParam: 单个参数描述,与
@ApiImplicitParam
不同的是,他是写在参数左侧的。如(@ApiParam(name = "username",value = "用户名") String username)@ApiModel: 描述
POJO
对象@ApiProperty: 描述
POJO
对象中的属性值@ApiImplicitParam: 描述单个入参信息
@ApiImplicitParams: 描述多个入参信息
@ApiResponse: 描述单个出参信息
@ApiResponses: 描述多个出参信息
@ApiError: 接口错误所返回的信息
package com.battcn.controller;
import com.battcn.entity.User;
import com.battcn.swagger.properties.ApiDataType;
import com.battcn.swagger.properties.ApiParamType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;
/**
* swagger
*
* @author Levin
* @since 2018/5/16 0016
*/
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用户管理", value = "用户管理")
public class UserController {
private static final Logger log = LoggerFactory.getLogger(UserController.class);
@GetMapping
@ApiOperation(value = "条件查询(DONE)")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
@ApiImplicitParam(name = "password", value = "密码", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
})
public User query(String username, String password) {
log.info("多个参数用 @ApiImplicitParams");
return new User(1L, username, password);
}
@GetMapping("/{id}")
@ApiOperation(value = "主键查询(DONE)")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
})
public User get(@PathVariable Long id) {
log.info("单个参数用 @ApiImplicitParam");
return new User(id, "u1", "p1");
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户(DONE)")
@ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
public void delete(@PathVariable Long id) {
log.info("单个参数用 ApiImplicitParam");
}
@PostMapping
@ApiOperation(value = "添加用户(DONE)")
public User post(@RequestBody User user) {
log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
return user;
}
@PutMapping("/{id}")
@ApiOperation(value = "修改用户(DONE)")
public void put(@PathVariable Long id, @RequestBody User user) {
log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
}
}
主函数
添加 @EnableSwagger2Doc
即可
package com.battcn;
import com.battcn.swagger.annotation.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* @author Levin
*/
@EnableSwagger2Doc
@SpringBootApplication
public class Chapter10Application {
public static void main(String[] args) {
SpringApplication.run(Chapter10Application.class, args);
}
}
测试
由于上面的接口是 restful 风格的接口,添加和修改无法通过浏览器完成,以前都是自己编写junit
或者使用postman
之类的工具。现在只需要打开浏览器输入 http://localhost:8080/swagger-ui.html,更多操作请自行体验…
总结
目前很多大佬都写过关于 SpringBoot 的教程了,如有雷同,请多多包涵,本教程基于最新的 spring-boot-starter-parent:2.0.2.RELEASE
编写,包括新版本的特性都会一起介绍…
说点什么
全文代码:https://github.com/battcn/spring-boot2-learning/tree/master/chapter10
欢迎加入我的知识星球,一起探讨架构,交流源码。加入方式,长按下方二维码噢:
已在知识星球更新源码解析如下:
《精尽 Dubbo 源码解析系列》69 篇。
《精尽 Netty 源码解析系列》61 篇。
《精尽 Spring 源码解析系列》35 篇。
《精尽 MyBatis 源码解析系列》34 篇。
《数据库实体设计》17 篇。
正在准备更新《精尽 Spring MVC 源码解析系列》
目前在知识星球更新了《Dubbo 源码解析》目录如下:
01. 调试环境搭建
02. 项目结构一览
03. 配置 Configuration
04. 核心流程一览
05. 拓展机制 SPI
06. 线程池
07. 服务暴露 Export
08. 服务引用 Refer
09. 注册中心 Registry
10. 动态编译 Compile
11. 动态代理 Proxy
12. 服务调用 Invoke
13. 调用特性
14. 过滤器 Filter
15. NIO 服务器
16. P2P 服务器
17. HTTP 服务器
18. 序列化 Serialization
19. 集群容错 Cluster
20. 优雅停机
21. 日志适配
22. 状态检查
23. 监控中心 Monitor
24. 管理中心 Admin
25. 运维命令 QOS
26. 链路追踪 Tracing
... 一共 69+ 篇
目前在知识星球更新了《Netty 源码解析》目录如下:
01. 调试环境搭建
02. NIO 基础
03. Netty 简介
04. 启动 Bootstrap
05. 事件轮询 EventLoop
06. 通道管道 ChannelPipeline
07. 通道 Channel
08. 字节缓冲区 ByteBuf
09. 通道处理器 ChannelHandler
10. 编解码 Codec
11. 工具类 Util
... 一共 61+ 篇
目前在知识星球更新了《数据库实体设计》目录如下:
01. 商品模块
02. 交易模块
03. 营销模块
04. 公用模块
... 一共 17+ 篇
目前在知识星球更新了《Spring 源码解析》目录如下:
01. 调试环境搭建
02. IoC Resource 定位
03. IoC BeanDefinition 载入
04. IoC BeanDefinition 注册
05. IoC Bean 获取
06. IoC Bean 生命周期
... 一共 35+ 篇
目前在知识星球更新了《MyBatis 源码解析》目录如下:
01. 调试环境搭建
02. 项目结构一览
03. MyBatis 面试题合集
04. MyBatis 学习资料合集
05. MyBatis 初始化
06. SQL 初始化
07. SQL 执行
08. 插件体系
09. Spring 集成
... 一共 34+ 篇
源码不易↓↓↓↓↓
点赞支持老艿艿↓↓