Swagger基础（OpenAPI2 + SpringFox）

左手的ㄟ右手 2023-10-07 22:30 26阅读 0赞

## 说明 ##

Swagger 基础示例。

使用 springfox 框架。

## 依赖 ##

<dependency>
    			<groupId>io.swagger</groupId>
    			<artifactId>swagger-annotations</artifactId>
    			<version>1.5.21</version>
    		</dependency>
    		<dependency>
    			<groupId>io.swagger</groupId>
    			<artifactId>swagger-models</artifactId>
    			<version>1.5.21</version>
    		</dependency>
    		
    		<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>

## 配置 application.properties ##

# 指定路径匹配规则。如果不指定，则Springfox和SpringBoot默认路径匹配规则冲突，会报错。
    spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

## 配置 SwaggerConfig ##

package com.example.swaggerdemo.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    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 SwaggerConfig {
    	@Bean
    	Docket createRestApi() {
    		return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
    //                .groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
    				.apiInfo(apiInfo()) // 用于生成API信息
    				.select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
    				.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo")) // 用于指定扫描哪个包下的接口
    				.paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
    				.build();
    	}
    
    	/**
    	 * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
    	 * 
    	 * @return
    	 */
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder().title("XX项目API") // 可以用来自定义API的主标题
    				.description("XX项目SwaggerAPI管理") // 可以用来描述整体的API
    				.termsOfServiceUrl("") // 用于定义服务的域名
    				.version("1.0") // 可以用来定义版本。
    				.build(); //
    	}
    }

## 注解 示例代码 ##

package com.example.swaggerdemo.user.controller;
    
    import java.util.Date;
    
    import javax.validation.Valid;
    
    import org.springframework.beans.BeanUtils;
    import org.springframework.web.bind.annotation.DeleteMapping;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.PutMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.example.swaggerdemo.user.entity.UserEntity;
    import com.example.swaggerdemo.user.vo.DateRangeVO;
    import com.example.swaggerdemo.user.vo.TimeRangeVO;
    import com.example.swaggerdemo.user.vo.UserAddVO;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    
    @RestController
    @RequestMapping("user")
    @Api(tags = "用户管理")
    public class UserController {
    
    	@PostMapping
    	@ApiOperation(value = "新增用户", notes = "新增用户，不能设置用户ID")
    	public String addUser(@ApiParam(value = "新增用户信息") @RequestBody @Valid UserAddVO user) {
    		System.out.println("添加用户: " + user.toString());
    		UserEntity userEntity = new UserEntity();
    		BeanUtils.copyProperties(user, userEntity);
    		userEntity.setId(12345);
    		return "添加用户成功";
    	}
    
    	@DeleteMapping("{userId}")
    	@ApiOperation(value = "删除用户", notes = "按照用户ID删除用户")
    	public String deleteUser(@ApiParam(value = "用户ID", example = "1001") @PathVariable Integer userId) {
    		UserEntity vo = new UserEntity();
    		vo.setId(userId);
    		System.out.println(vo.toString());
    		return "删除用户 " + userId + " 成功";
    	}
    
    	@PutMapping
    	@ApiOperation(value = "更新用户信息", notes = "添加用户，必须包含用户ID")
    	public String updateUser(@ApiParam(value = "更新用户信息") @RequestBody @Valid UserEntity user) {
    		System.out.println(user.toString());
    		return "更新用户成功";
    	}
    
    	@GetMapping("{userId}")
    	@ApiOperation(value = "查询用户信息", notes = "按照用户ID，查询用户信息")
    	public UserEntity getUser(@ApiParam(value = "用户ID", example = "1001") @PathVariable Integer userId) {
    		UserEntity user = new UserEntity();
    		user.setId(userId);
    		user.setName("李四");
    		user.setGender("男");
    		user.setBeginDate(new Date());
    		user.setBeginTime(new Date());
    		return user;
    	}
    
    	@GetMapping("findByDate")
    	@ApiOperation(value = "查询用户信息，参数：日期范围", notes = "查询用户信息，查询条件位 日期范围")
    	public UserEntity getUserByDateRange(@Valid DateRangeVO dateRange) {
    		System.out.println("查询用户信息: " + dateRange.toString());
    		UserEntity user = new UserEntity();
    		user.setId(2001);
    		user.setName("赵一");
    		user.setGender("男");
    		user.setBeginDate(dateRange.getBeginDate());
    		user.setEndDate(dateRange.getEndDate());
    		return user;
    	}
    
    	@GetMapping("findByTime")
    	@ApiOperation(value = "查询用户信息，参数：时间范围", notes = "查询用户信息，查询条件位 时间范围")
    	public UserEntity getUserByTimeRange(@Valid TimeRangeVO vo) {
    		System.out.println("查询用户信息: " + vo.toString());
    		UserEntity user = new UserEntity();
    		user.setId(2001);
    		user.setName("赵一");
    		user.setGender("男");
    		user.setBeginTime(vo.getBeginTime());
    		user.setEndTime(vo.getEndTime());
    		return user;
    	}
    }

package com.example.swaggerdemo.user.entity;
    
    import java.util.Date;
    
    import javax.validation.constraints.NotNull;
    
    import com.fasterxml.jackson.annotation.JsonFormat;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "User", description = "用户")
    public class UserEntity {
    
    	@NotNull
    	@ApiModelProperty(value = "用户ID", example = "1001", name = "userId")
    	private Integer id;
    
    	@ApiModelProperty(value = "姓名", example = "张三")
    	private String name;
    
    	@ApiModelProperty(value = "性别", example = "男")
    	private String gender;
    
    	@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    	@ApiModelProperty(value = "开始日期", example = "2023-01-01")
    	private Date beginDate;
    
    	@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    	@ApiModelProperty(value = "结束日期", example = "2023-01-02")
    	private Date endDate;
    
    	@ApiModelProperty(value = "开始时间", example = "2022-12-31 01:10:20")
    	private Date beginTime;
    
    	@ApiModelProperty(value = "结束时间", example = "2022-12-31 12:30:40")
    	private Date endTime;
    
    }

package com.example.swaggerdemo.user.vo;
    
    import java.util.Date;
    
    import javax.validation.constraints.NotBlank;
    
    import com.fasterxml.jackson.annotation.JsonFormat;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "UserAddVO", description = "新增用户")
    public class UserAddVO {
    
    	@NotBlank
    	@ApiModelProperty(value = "姓名", example = "张三")
    	private String name;
    
    	@ApiModelProperty(value = "性别", example = "男")
    	private String gender;
    
    	@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    	@ApiModelProperty(value = "开始日期", example = "2023-01-01")
    	private Date beginDate;
    
    	@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    	@ApiModelProperty(value = "结束日期", example = "2023-01-02")
    	private Date endDate;
    
    	@ApiModelProperty(value = "开始时间", example = "2022-12-31 01:10:20")
    	private Date beginTime;
    
    	@ApiModelProperty(value = "结束时间", example = "2022-12-31 12:30:40")
    	private Date endTime;
    
    }

package com.example.swaggerdemo.user.vo;
    
    import java.util.Date;
    
    import org.springframework.format.annotation.DateTimeFormat;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "DateRange", description = "日期范围")
    public class DateRangeVO {
    
    	@ApiModelProperty(value = "开始日期", example = "2023-01-01")
    	@DateTimeFormat(pattern = "yyyy-MM-dd")
    	private Date beginDate;
    
    	@ApiModelProperty(value = "结束日期", example = "2023-01-02")
    	@DateTimeFormat(pattern = "yyyy-MM-dd")
    	private Date endDate;
    
    }

package com.example.swaggerdemo.user.vo;
    
    import java.util.Date;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "TimeRange", description = "时间范围")
    public class TimeRangeVO {
    
    	@ApiModelProperty(value = "开始时间", example = "2023-01-01 01:20:30")
    	private Date beginTime;
    
    	@ApiModelProperty(value = "结束时间", example = "2023-01-02 12:30:40")
    	private Date endTime;
    
    }

## API文档效果 ##

![051bba3068e948729a517b0a5f897f5c.png][]

[051bba3068e948729a517b0a5f897f5c.png]: https://img-blog.csdnimg.cn/051bba3068e948729a517b0a5f897f5c.png