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