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


點擊測試