高併發架構實戰(六) Spring Boot 整合 Swagger2
阿新 • • 發佈:2018-12-13
Spring Boot 2.0.4 整合 swagger 2.9.2。 專案原始碼地址
一、簡介
Swagger是一款Restful介面的文件線上自動生成的軟體,也能進行功能測試。
二、使用方法
先看下目錄結構
~/workspace/gitee/high-concurrency on master ⌚ 12:52:03 $ tree -I target . ├── README.md ├── common │ ├── pom.xml │ └── src │ └── main │ ├── java │ │ └── cn │ │ └── lilyssh │ │ └── common │ │ └── swagger │ │ ├── Swagger2Config.java │ │ └── SwaggerProperties.java │ └── resources │ └── META-INF │ └── spring.factories ├── order │ ├── order-api │ │ ├── pom.xml │ │ └── src │ │ └── main │ │ └── java │ │ └── cn.lilyssh.order.api │ │ ├── model │ │ │ ├── request │ │ │ │ ├── OrderInsertReq.java │ │ │ │ └── OrderQueryReq.java │ │ │ └── response │ │ │ └── OrderQueryResp.java │ │ └── service │ │ └── OrderServiceApi.java │ └── order-consumer │ ├── pom.xml │ └── src │ └── main │ ├── java │ │ └── cn │ │ └── lilyssh │ │ └── order │ │ └── consumer │ │ ├── OrderConsumerApplication.java │ │ ├── controller │ │ │ └── OrderController.java │ │ └── service │ │ └── OrderService.java │ └── resources │ ├── application.yml │ └── bootstrap.yml └── pom.xml
1、common專案
(1)新增swagger依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
(2)新建Swagger的配置類
package cn.lilyssh.common.swagger;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@EnableConfigurationProperties({SwaggerProperties.class})
public class Swagger2Config {
@Autowired
private SwaggerProperties swaggerProperties;
/**
* 新增摘要資訊(Docket)
*/
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(true)
.apiInfo(new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.contact(new Contact(swaggerProperties.getAuthor(), swaggerProperties.getUrl(), swaggerProperties.getEmail()))
.version(swaggerProperties.getVersion())
.build())
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
.paths(PathSelectors.any())
.build();
}
}
package cn.lilyssh.common.swagger;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {
private boolean enable;
private String title;
private String description;
private String author;
private String email;
private String version;
private String basePackage;
private String url;
}
(3)配置spring掃描路徑
spring.factories
中內容為
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
cn.lilyssh.common.exception.ExceptionAdviceHandler,\
cn.lilyssh.common.swagger.Swagger2Config
換行要用\。
2、order-consumer專案
(1)新增common依賴
<dependency>
<groupId>cn.lilyssh</groupId>
<artifactId>common</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
(2)在啟動類中新增@EnableSwagger2註解
package cn.lilyssh.order.consumer;
import com.alibaba.dubbo.spring.boot.annotation.EnableDubboConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 開啟線上介面文件
*/
@EnableSwagger2
@SpringBootApplication
@EnableDubboConfiguration
public class OrderConsumerApplication {
public static void main(String[] args) {
SpringApplication.run(OrderConsumerApplication.class, args);
}
}
(3)在application.yml中新增配置
swagger:
title : lilyssh_電商系統_介面文件
description : 用於網上購物的訂單模組
author : lily
url : lilyssh.cn
email : [email protected]
version : 版本號:1.0
basePackage : cn.lilyssh.order.consumer.controller
(4)在controller中添加註解
package cn.lilyssh.order.consumer.controller;
import cn.lilyssh.common.result.Result;
import cn.lilyssh.common.validate.ValidateGroup;
import cn.lilyssh.order.api.model.request.OrderInsertReq;
import cn.lilyssh.order.api.model.request.OrderQueryReq;
import cn.lilyssh.order.consumer.service.OrderService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.AllArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
@Api(description = "訂單介面")
@RestController
@AllArgsConstructor
@RequestMapping("/order")
public class OrderController {
private OrderService orderService;
@ApiOperation("獲取所有訂單")
@GetMapping
public Result orderList(OrderQueryReq orderQueryReq){
return orderService.orderList(orderQueryReq);
}
@ApiOperation("下單")
@PostMapping
public Result save(@RequestBody @Validated(value = ValidateGroup.Insert.class) OrderInsertReq orderInsertReq){
return orderService.save(orderInsertReq);
}
}
3、order-api專案
(1)在實體類中添加註解
package cn.lilyssh.order.api.model.request;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.models.properties.BaseIntegerProperty;
import lombok.Data;
import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Date;
@Data
@ApiModel(description = "訂單查詢請求資料")
public class OrderQueryReq implements Serializable {
@ApiModelProperty(value = "訂單ID")
private Integer id;
@ApiModelProperty(value = "使用者ID")
private Integer userId;
private String userUuid;
private BigDecimal payment;
private Integer payType;
private BigDecimal postFee;
private Integer status;
private Date createTime;
private Date updateTime;
private Date payTime;
private Date cosignTime;
private Date endTime;
private Date closeTime;
private String shippingName;
private String shippingCode;
}
訪問http://localhost:1111/swagger-ui.html
,報錯:Illegal DefaultValue null for parameter type integer.
,解決辦法:
實體類中,Integer型別的屬性加@ApiModelProperty時,必須要給example引數賦值,且值必須為數字型別。
@Data
@ApiModel(description = "訂單查詢請求資料")
public class OrderQueryReq implements Serializable {
@ApiModelProperty(value = "訂單ID",example = "123")
private Integer id;
}