SpringBoot---Swagger文档管理应用

1、添加依赖

<dependencies>
		<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>
	</dependencies>

2、创建独立的Maven子模块

a、Swagger配置类

package com.imooc;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StringUtils;

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.ApiSelectorBuilder;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
//@EnableConfigurationProperties(SwaggerInfo.class)
public class SwaggerConfig {
	
	@Autowired
	private SwaggerInfo swaggerInfo;

	@Bean
	public Docket controllerApi(){
		System.out.println("======swaggerInfo====="+swaggerInfo);
		Docket docket = new Docket(DocumentationType.SWAGGER_2)
				.groupName(swaggerInfo.getGroupName()) // 分组名
				.apiInfo(apiInfo());
		ApiSelectorBuilder builder = docket.select();
		if(!StringUtils.isEmpty(swaggerInfo.getBasePackage())){
			builder = builder.apis(RequestHandlerSelectors.basePackage(swaggerInfo.getBasePackage())); // 筛选显示接口
		}
		if(!StringUtils.isEmpty(swaggerInfo.getAntPath())){
			builder = builder.paths(PathSelectors.ant(swaggerInfo.getAntPath()));
		}
		
		return builder.build();
	}
	
	public ApiInfo apiInfo(){
		return new ApiInfoBuilder()
				.title(swaggerInfo.getTitle())
				.description(swaggerInfo.getDescription())
				.termsOfServiceUrl("http://springfox.io")
				.contact("imooc")
				.license(swaggerInfo.getLicense())
				.version("2.0")
				.build();
	}
}

属性配置类

package com.imooc;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * Swagger配置信息
 * @author zemel
 *
 */
@Component
@ConfigurationProperties(prefix="swagger", ignoreUnknownFields = true)
public class SwaggerInfo {

	private String groupName = "controller";
	private String basePackage;
	private String antPath;
	private String title = "HTTP API";
	private String description = "管理端接口";
	private String license = "Apache License Version 2.0";
	public String getGroupName() {
		return groupName;
	}
	public void setGroupName(String groupName) {
		this.groupName = groupName;
	}
	public String getBasePackage() {
		return basePackage;
	}
	public void setBasePackage(String basePackage) {
		this.basePackage = basePackage;
	}
	public String getAntPath() {
		return antPath;
	}
	public void setAntPath(String antPath) {
		this.antPath = antPath;
	}
	public String getTitle() {
		return title;
	}
	public void setTitle(String title) {
		this.title = title;
	}
	public String getDescription() {
		return description;
	}
	public void setDescription(String description) {
		this.description = description;
	}
	public String getLicense() {
		return license;
	}
	public void setLicense(String license) {
		this.license = license;
	}
	@Override
	public String toString() {
		return "SwaggerInfo [groupName=" + groupName + ", basePackage=" + basePackage + ", antPath=" + antPath
				+ ", title=" + title + ", description=" + description + ", license=" + license + "]";
	}
	
}

b、其他工程应用方法有三种

1）一种直接在App.java中使用@Import注解导入配置类

@SpringBootApplication
//@EnableMySwagger
@Import(SwaggerConfig.class)
public class App {

	public static void main(String[] args) {
		SpringApplication.run(App.class, args);
	}
}

2）编写@Enable*的注解，在App.java中启用

package com.imooc;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import org.springframework.context.annotation.Import;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value = { java.lang.annotation.ElementType.TYPE })
@Documented
@Import({SwaggerConfig.class})
@EnableSwagger2 // 组合注解
public @interface EnableMySwagger {

}

@SpringBootApplication
@EnableMySwagger
public class App {

	public static void main(String[] args) {
		SpringApplication.run(App.class, args);
	}
}

3）在resource/META_INF/spring.factories下配置Config类

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.imooc.SwaggerConfig

3、在应用Swagger工程配置文件(application.properties)

# 配置swagger
swagger.groupName=manager
swagger.basePackage=com.imooc.controller

4、Swagger功能使用

控制器，主要注释带@ApiXX

package com.imooc.controller;

import java.math.BigDecimal;
import java.util.Arrays;
import java.util.List;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.util.StringUtils;
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.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.imooc.entity.Product;
import com.imooc.service.ProductService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/products")
@Api(tags="order", description="产品相关")
public class ProductController {

	private static Logger log = LoggerFactory.getLogger(ProductController.class);
 
	@Autowired
	private ProductService productService;
	
	@ApiOperation(notes="根据队员业务规划添加相应产品", value="创建产品")
	@PostMapping
	public Product addProduct(@RequestBody Product product){
		
		log.debug("创建产品，参数：{}",product);
		
		Product result = productService.addProduct((product));
		
		log.debug("创建产品，结果：{}",result);
		
		return result;
	}
	
	@GetMapping("/{id}")
	public Product findOne(@PathVariable String id){
		log.debug("查询单个产品，id={}", id);
		
		Product product = productService.findOne(id);
		
		log.debug("查询单个产品，结果={}", product);
		return product;
	}
	
	@GetMapping
	public Page<Product> query(String ids, BigDecimal minRewardRate, BigDecimal maxRewardRate, String status, 
			@RequestParam(defaultValue = "0")int pageNum, @RequestParam(defaultValue = "10") int pageSize){
		
		log.info("查询产品，idList={},minRewardRate={},maxRewardRate={},statusList={},pageNum={},pageSize={}",ids, minRewardRate,maxRewardRate,status,pageNum,pageSize);
		
		List<String> idList = null;
		List<Integer> statusList = null;
		if(!StringUtils.isEmpty(ids)){
			idList = Arrays.asList(ids.split(","));
		}
		if(!StringUtils.isEmpty(statusList)){
			String[] statusStr = status.split(",");
//			statusStr.m
			Integer[] statusInt = new Integer[statusStr.length];
			for(int i=0; i<statusStr.length; i++){
				statusInt[i] = Integer.parseInt(statusStr[i]);
			}
			statusList = Arrays.asList(statusInt);
		}
		
		Pageable pageable = PageRequest.of(pageNum, pageSize);
		Page<Product> page = productService.query(idList, minRewardRate, maxRewardRate, statusList, pageable);
		log.info("查询产品，结果={}", page);
		
		return page;
	}
	
}

实体类中使用

@ApiModel(value="ppp", description="产品模型")
@Entity
@Table(name="product_t")
public class Product {
	
	@Id
	@Column(name="id",columnDefinition="varchar(50) comment '产品编号'")
	private String id;
	
	@Column(name="name",columnDefinition="varchar(50) not null default '' comment '产品名称'")
	private String name;
	
	/**
	 * @see com.imooc.entity.enums.ProductStatus
	 */
	@ApiModelProperty(value="状态", dataType="com.imooc.entity.enums.ProductStatus")
	@Column(name="status",columnDefinition="smallint(6) not null default 0 comment '状态，1:审核中、2:销售中、3:暂停销售、4:已结束' ")
	private Integer status;
}