Spring Boot 2.0.4 集成 swagger 2.9.2。
项目源码地址 ：https://gitee.com/lilyssh/high-concurrency
一、简介
Swagger是一款Restful接口的文档在线自动生成的软件，也能进行功能测试。
二、使用方法
先看下目录结构
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
| 1~/workspace/gitee/high-concurrency on master ⌚ 12:52:03
2$ tree -I target
3.
4├── README.md
5├── common
6│ ├── pom.xml
7│ └── src
8│ └── main
9│ ├── java
10│ │ └── cn
11│ │ └── lilyssh
12│ │ └── common
13│ │ └── swagger
14│ │ ├── Swagger2Config.java
15│ │ └── SwaggerProperties.java
16│ └── resources
17│ └── META-INF
18│ └── spring.factories
19├── order
20│ ├── order-api
21│ │ ├── pom.xml
22│ │ └── src
23│ │ └── main
24│ │ └── java
25│ │ └── cn.lilyssh.order.api
26│ │ ├── model
27│ │ │ ├── request
28│ │ │ │ ├── OrderInsertReq.java
29│ │ │ │ └── OrderQueryReq.java
30│ │ │ └── response
31│ │ │ └── OrderQueryResp.java
32│ │ └── service
33│ │ └── OrderServiceApi.java
34│ └── order-consumer
35│ ├── pom.xml
36│ └── src
37│ └── main
38│ ├── java
39│ │ └── cn
40│ │ └── lilyssh
41│ │ └── order
42│ │ └── consumer
43│ │ ├── OrderConsumerApplication.java
44│ │ ├── controller
45│ │ │ └── OrderController.java
46│ │ └── service
47│ │ └── OrderService.java
48│ └── resources
49│ ├── application.yml
50│ └── bootstrap.yml
51└── pom.xml
52
53
54 |
1、common项目
（1）添加swagger依赖
1
2
3
4
5
6
7
8
9
10
11
12
| 1<dependency>
2 <groupId>io.springfox</groupId>
3 <artifactId>springfox-swagger-ui</artifactId>
4 <version>2.9.2</version>
5</dependency>
6<dependency>
7 <groupId>io.springfox</groupId>
8 <artifactId>springfox-swagger2</artifactId>
9 <version>2.9.2</version>
10</dependency>
11
12 |
（2）新建Swagger的配置类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
| 1package cn.lilyssh.common.swagger;
2
3import org.springframework.beans.factory.annotation.Autowired;
4import org.springframework.boot.context.properties.EnableConfigurationProperties;
5import org.springframework.context.annotation.Bean;
6import springfox.documentation.builders.ApiInfoBuilder;
7import springfox.documentation.builders.PathSelectors;
8import springfox.documentation.builders.RequestHandlerSelectors;
9import springfox.documentation.service.Contact;
10import springfox.documentation.spi.DocumentationType;
11import springfox.documentation.spring.web.plugins.Docket;
12
13@EnableConfigurationProperties({SwaggerProperties.class})
14public class Swagger2Config {
15
16 @Autowired
17 private SwaggerProperties swaggerProperties;
18 /**
19 * 添加摘要信息(Docket)
20 */
21 @Bean
22 public Docket controllerApi() {
23 return new Docket(DocumentationType.SWAGGER_2)
24 .enable(true)
25 .apiInfo(new ApiInfoBuilder()
26 .title(swaggerProperties.getTitle())
27 .description(swaggerProperties.getDescription())
28 .contact(new Contact(swaggerProperties.getAuthor(), swaggerProperties.getUrl(), swaggerProperties.getEmail()))
29 .version(swaggerProperties.getVersion())
30 .build())
31 .select()
32 .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
33 .paths(PathSelectors.any())
34 .build();
35 }
36}
37
38 |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| 1package cn.lilyssh.common.swagger;
2
3import lombok.Data;
4import org.springframework.boot.context.properties.ConfigurationProperties;
5
6@Data
7@ConfigurationProperties(prefix = "swagger")
8public class SwaggerProperties {
9 private boolean enable;
10 private String title;
11 private String description;
12 private String author;
13 private String email;
14 private String version;
15 private String basePackage;
16 private String url;
17}
18
19 |
（3）配置spring扫描路径
spring.factories中内容为
1
2
3
4
5
| 1org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
2 cn.lilyssh.common.exception.ExceptionAdviceHandler,\
3 cn.lilyssh.common.swagger.Swagger2Config
4
5 |
换行要用\。
2、order-consumer项目
（1）添加common依赖
1
2
3
4
5
6
7
| 1<dependency>
2 <groupId>cn.lilyssh</groupId>
3 <artifactId>common</artifactId>
4 <version>0.0.1-SNAPSHOT</version>
5</dependency>
6
7 |
（2）在启动类中添加@EnableSwagger2注解
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| 1package cn.lilyssh.order.consumer;
2
3import com.alibaba.dubbo.spring.boot.annotation.EnableDubboConfiguration;
4import org.springframework.boot.SpringApplication;
5import org.springframework.boot.autoconfigure.SpringBootApplication;
6import springfox.documentation.swagger2.annotations.EnableSwagger2;
7
8/**
9 * 开启在线接口文档
10 */
11@EnableSwagger2
12@SpringBootApplication
13@EnableDubboConfiguration
14public class OrderConsumerApplication {
15
16 public static void main(String[] args) {
17 SpringApplication.run(OrderConsumerApplication.class, args);
18 }
19}
20
21 |
（3）在application.yml中添加配置
1
2
3
4
5
6
7
8
9
10
| 1swagger:
2 title : lilyssh_电商系统_接口文档
3 description : 用于网上购物的订单模块
4 author : lily
5 url : lilyssh.cn
6 email : 1643995620@qq.com
7 version : 版本号:1.0
8 basePackage : cn.lilyssh.order.consumer.controller
9
10 |
（4）在controller中添加注解
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
| 1package cn.lilyssh.order.consumer.controller;
2
3import cn.lilyssh.common.result.Result;
4import cn.lilyssh.common.validate.ValidateGroup;
5import cn.lilyssh.order.api.model.request.OrderInsertReq;
6import cn.lilyssh.order.api.model.request.OrderQueryReq;
7import cn.lilyssh.order.consumer.service.OrderService;
8import io.swagger.annotations.Api;
9import io.swagger.annotations.ApiOperation;
10import lombok.AllArgsConstructor;
11import org.springframework.validation.annotation.Validated;
12import org.springframework.web.bind.annotation.*;
13
14@Api(description = "订单接口")
15@RestController
16@AllArgsConstructor
17@RequestMapping("/order")
18public class OrderController {
19
20 private OrderService orderService;
21
22 @ApiOperation("获取所有订单")
23 @GetMapping
24 public Result orderList(OrderQueryReq orderQueryReq){
25 return orderService.orderList(orderQueryReq);
26 }
27
28 @ApiOperation("下单")
29 @PostMapping
30 public Result save(@RequestBody @Validated(value = ValidateGroup.Insert.class) OrderInsertReq orderInsertReq){
31 return orderService.save(orderInsertReq);
32 }
33}
34
35 |
3、order-api项目
（1）在实体类中添加注解
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
| 1package cn.lilyssh.order.api.model.request;
2
3
4import io.swagger.annotations.ApiModel;
5import io.swagger.annotations.ApiModelProperty;
6import io.swagger.models.properties.BaseIntegerProperty;
7import lombok.Data;
8
9import java.io.Serializable;
10import java.math.BigDecimal;
11import java.util.Date;
12
13@Data
14@ApiModel(description = "订单查询请求数据")
15public class OrderQueryReq implements Serializable {
16
17 @ApiModelProperty(value = "订单ID")
18 private Integer id;
19 @ApiModelProperty(value = "用户ID")
20 private Integer userId;
21 private String userUuid;
22 private BigDecimal payment;
23 private Integer payType;
24 private BigDecimal postFee;
25 private Integer status;
26 private Date createTime;
27 private Date updateTime;
28 private Date payTime;
29 private Date cosignTime;
30 private Date endTime;
31 private Date closeTime;
32 private String shippingName;
33 private String shippingCode;
34}
35
36 |
访问http://localhost:1111/swagger-ui.html，报错:Illegal DefaultValue null for parameter type integer.，解决办法：
实体类中，Integer类型的属性加@ApiModelProperty时，必须要给example参数赋值，且值必须为数字类型。
1
2
3
4
5
6
7
8
| 1@Data
2@ApiModel(description = "订单查询请求数据")
3public class OrderQueryReq implements Serializable {
4 @ApiModelProperty(value = "订单ID",example = "123")
5 private Integer id;
6}
7
8 |
异常分析过程 请参考：swagger2异常:java.lang.NumberFormatException:For input string:""
再次访问
大功告成！
