Swagger学习

Swagger

学习视频：【狂神说Java】一小时掌握Swagger技术
即使再小的帆也能远航

学习目标

• 了解Swagger的作用和概念
• 巩固前后端分离的概念

Swagger简介

前后端分离现在主流的技术栈（2020）
Vue+SpringBoot

后端时代：

前端只用管理静态页面；html==》后端，模板引擎==》后端是主力

前后端分离时代：

• 后端：控制层，业务层，业务访问层
• 前端：控制层，视图层

伪造后端数据，json已经存在，不需要后端也能跑起来
前后端交互 ==》API
前后端相互独立，松耦合

产生出问题：

前后端集成联调，前端人员和后端人员无法做到及时协商最终导致问题爆发

解决方案：

首先指定schema【计划的提纲】，实时更新最新API，降低集成的风险；

• 早些年：制定word计划文档；

• 前后端分离：

  • 前端测试后端接口：postman
  • 后端提供接口，需要实时更新最新的API

Swagger简介

号称世界上最流行的API框架

RestFul API文档自动生成工具 ==》API文档与API定义同步更新
直接运行，可在线测试API接口

支持多种语言
官网：https://swagger.io/

在项目中使用Swagger需要springbox：

• swagger2
• swagger-ui

Springboot集成Swagger

1. 新建springboot-web项目
2. 导入相关依赖
   1. 使用Springboot集成starter依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

2.使用官方依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3. 编写一个Hello项目
   • 开启Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

3. 效果：访问localhost:8080/swagger-ui.html
   

配置

Swagger的bean实例Docket；

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
	public Docket docket() {
		Docket docket = new Docket(DocumentationType.SWAGGER_2);
		ApiInfo apiInfo = new ApiInfo(
				"留言板", 
				"java程序员进阶之路", 
				"1.5", 
				"https://github.com", 
				new Contact("Esion", "https://github.com/q2316367743", "m17762618644@163.com"), 
				"Apache License, Version 2.0", 
				"https://www.apache.org/licenses/LICENSE-2.0.html", 
				new ArrayList<>()
		);
		docket.apiInfo(apiInfo);
		return docket;
	}

}

Swagger配置扫描接口

docket.select()
      .apis(RequestHandlerSelectors.basePackage("com.qsd.messageboard"))
	  .build();

根据当前环境决定是否开启Swagger

配置API文档的分组

docket.groupName("Esion");

配置多个分组

配置多个Docket实例即可

常见注解

最常用的5个注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段

其它若干

@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit

示例

@Api()，@ApiOperation()，@ApiParam()

@RestController
@RequestMapping("message")
@Api(value = "留言操作类")
public class MessageController {
	
	@Autowired
	private MessageService messageService;
	
	@ApiOperation(value = "新增留言")
	@PostMapping("add")
	public BaseVo add(
			@ApiParam(value = "留言标题", required = true) String title,
			@ApiParam(value = "留言内容", required = true)String content, 
			HttpServletRequest request) {
		if (title == null || content == null) {
			return new BaseVo(ResultStatus.REQUEST_PARAM_MISS);
		}
		User user = (User) request.getSession().getAttribute("user");
		return new BaseVo(messageService.add(title, content, user.getId()));
	}
 }

@ApiModel()，@ApiModelProperty()

@ApiModel(description = "留言信息")
public class Message {
	
	@ApiModelProperty(value = "留言ID", required = false, example = "1")
	private Integer id;
	@ApiModelProperty(value = "留言的用户ID")
	private String userId;
	@ApiModelProperty(value = "留言的标题")
	private String title;
	@ApiModelProperty(value = "留言的创建时间")
	private Timestamp createTime;
	@ApiModelProperty(value = "留言的内容")
	private String content;
	private User user;
 }