springboot整合接口管理工具Swagger2

在前后端分离开发中，为了减少与其它团队的沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端，不仅编写文档工作量巨大，而且维护不方便，测试也不方便（需要借助第三方工具，如 Postman 来测试） 为解决这些问题，可以使用 Swagger 2 来构建在线接口文档.

什么是 Swagger 2

Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

SpringBoot整合Swagger2

导入依赖

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

• 首先通过 @EnableSwagger2 注解开启了 Swagger 2，然后最主要的是配置一个 Docket。
• 通过 apis 方法配置要扫描的 controller 位置，通过 paths 方法配置路径。
• 在 apiInfo 中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

在接口控制类添加注解

• @Api 注解标注在类上用来描述整个 Controller 信息。
• @ApiOperation 注解标注在方法上，用来描述一个方法的基本信息。
• @ApiImplicitParam 注解标注在方法上，用来描述方法的参数。其中 paramType 是指方法参数的类型，有如下可选值：
  • path：参数获取方式为 @PathVariable
  • query：参数获取方式为 @RequestParam
  • header：参数获取方式为 @RequestHeader
  • body
  • form
• 如果有多个参数，可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
• @ApiResponse 是对响应结果的描述。code 表示响应码，message 为相应的描述信息。如果有多个@ApiResponse，则放在一个 @ApiResponses 中。
• @ApiIgnore 注解表示不对某个接口生成文档。

@Api(tags = "无聊测试相关接口")
@Controller
public class DemoController {
	@Autowired
	DemoService demoservice;

	@ResponseBody
	@GetMapping("/demo")
	@ApiOperation("第一次启动测试接口")
	public String deno() {
		demoservice.insert();
		return "hello world";
	}

//分页查询
	@ResponseBody
	@GetMapping("/cc")
	@ApiOperation(value = "分页查询接口", notes = "随机分页测试")
	public List<Tuser> pageQuery() {
		Random rd = new Random();
		Integer page = rd.nextInt(10) + 1;
		List<Tuser> list = demoservice.pageQuery(page);
		System.out.println(list.toString());
		return list;
	}

	// 根据商品id查询对象数据
	@ResponseBody
	@GetMapping(value = "product/{productId}")
	@ApiImplicitParam(paramType = "path", name = "id", value = "商品 id", required = true)
	 @ApiResponses({
         @ApiResponse(code = 200, message = "返回商品！"),
         @ApiResponse(code = 500, message = "查询失败！")
 })
	@ApiOperation(value = "查询对象", notes = "根据id查询")
	public Product queryByid(@PathVariable Integer productId) {
		// 控制层无需处理数据调用，业务逻辑
		Product product = demoservice.queryById(productId);
		return product;
	}

	Product product = new Product(null, "飞科剃须刀", 654.0, 654150, "就是快");

	// 新增商品数据到数据库
	@ResponseBody
	@RequestMapping(value = "product/saveProduct")
	public int saveProduct() {
		try {
			demoservice.saveProduct(product);
			return 1;
		} catch (Exception e) {
			e.printStackTrace();
			return 0;
		}
	}

	@ResponseBody
	@RequestMapping("product/updateProduct")
	public Integer updateProduct(Product product) {
		try {
			Product product1 = new Product(1, "波导手机", 565654.0, 220, "就是好看得不行");
			demoservice.updateProductById(product1);
			return 1;
		} catch (Exception e) {
			e.printStackTrace();
			return 0;
		}
	}
}

通过 @ApiModel 注解和 @ApiModelProperty 注解配置 Product对象的描述信息。

@ApiModel(value = "商品实体类", description = "商品信息描述类")
public class Product {
	// 根据数据库表格结构类型，完成属性封装
	// 定义了封装持久层对象的驼峰命名
	@ApiModelProperty(value = "商品id")
	private Integer productId;
	@ApiModelProperty(value = "商品名")
	private String productName;
	@ApiModelProperty(value = "商品价格")
	private Double productPrice;
	@ApiModelProperty(value = "商品数量")
	private Integer productNum;
	@ApiModelProperty(value = "商品描述")
	private String productDescription;
	public Product() {
		super();
		// TODO Auto-generated constructor stub
	}
	public Product(Integer productId, String productName, Double productPrice, Integer productNum,
			String productDescription) {
		super();
		this.productId = productId;
		this.productName = productName;
		this.productPrice = productPrice;
		this.productNum = productNum;
		this.productDescription = productDescription;
	}
	@Override
	public String toString() {
		return "Product [productId=" + productId + ", productName=" + productName + ", productPrice=" + productPrice
				+ ", productNum=" + productNum + ", productDescription=" + productDescription + "]";
	}
	public Integer getProductId() {
		return productId;
	}
	public void setProductId(Integer productId) {
		this.productId = productId;
	}
	public String getProductName() {
		return productName;
	}
	public void setProductName(String productName) {
		this.productName = productName;
	}
	public Double getProductPrice() {
		return productPrice;
	}
	public void setProductPrice(Double productPrice) {
		this.productPrice = productPrice;
	}
	public Integer getProductNum() {
		return productNum;
	}
	public void setProductNum(Integer productNum) {
		this.productNum = productNum;
	}
	public String getProductDescription() {
		return productDescription;
	}
	public void setProductDescription(String productDescription) {
		this.productDescription = productDescription;
	}

	
}

访问http://localhost:8093/swagger-ui.html


点击测试