今天在项目中使用Swagger说明配置,感觉不错,先上效果图
1.maven配置
在pom.xml文件中引入这两个配置
<!--Swagger-UI API文档生产工具-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
2.创建配置文件
package com.bjshengeng.cooperate.vcps.wms.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* Swagger2API文档的配置
*
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.bjshengeng.cooperate.vcps.wms.controller"))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("WMS后台系统")
.description("WMS后台模块")
.contact("shengeng")
.version("1.0")
.build();
}
private List<ApiKey> securitySchemes() {
//设置请求头信息
List<ApiKey> result = new ArrayList<>();
ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
result.add(apiKey);
return result;
}
private List<SecurityContext> securityContexts() {
//设置需要登录认证的路径
List<SecurityContext> result = new ArrayList<>();
// result.add(getContextByPath("/brand/.*"));
// result.add(getContextByPath("/product/.*"));
// result.add(getContextByPath("/productCategory/.*"));
return result;
}
private SecurityContext getContextByPath(String pathRegex){
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex(pathRegex))
.build();
}
private List<SecurityReference> defaultAuth() {
List<SecurityReference> result = new ArrayList<>();
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
result.add(new SecurityReference("Authorization", authorizationScopes));
return result;
}
}
3.设置Swagger相关属性
@Api 标注在api上
@ApiOperation 标注在方法上
@ApiParam 标注在参数上
@ApiModelProperty 标注在实体对象字段上
package com.bjshengeng.cooperate.vcps.wms.controller;
import com.alibaba.druid.util.StringUtils;
import com.bjshengeng.cooperate.vcps.core.CommonPage;
import com.bjshengeng.cooperate.vcps.core.CommonResult;
import com.bjshengeng.cooperate.vcps.wms.core.domain.*;
import com.bjshengeng.cooperate.vcps.wms.core.dto.*;
import com.bjshengeng.cooperate.vcps.wms.core.enums.*;
import com.bjshengeng.cooperate.vcps.wms.core.service.*;
import com.bjshengeng.cooperate.vcps.wms.core.utils.DateUtil;
import com.google.common.base.Strings;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
@RestController
@Api(tags = "BadController", description = "报残管理")
@RequestMapping("/bad")
public class BadController {
@Autowired
private BadService badService;
@Autowired
private BadLocationDetailService badLocationDetailService;
@Autowired
private LocationsService locationsService;
@Autowired
private LocationExpiryStockService locationExpiryStockService;
@Autowired
private LocationFormRelationService locationFormRelationService;
@Autowired
private CustomerInfoService customerInfoService;
@ApiOperation(value = "根据单号查询货位明细")
@RequestMapping(value = "/getlistbyorderno", method = RequestMethod.GET)
@ResponseBody
public CommonResult<List<BadLocationDetail>> getListByOrderNo(@RequestParam("orderno") @ApiParam(value = "报残单号") String orderNo) {
if (orderNo==null|| StringUtils.isEmpty(orderNo))
{
return CommonResult.failed("单号不能为空");
}
List<BadLocationDetail> list = badLocationDetailService.getListByOrderNo(orderNo);
return CommonResult.success(list);
}
}
package com.bjshengeng.cooperate.vcps.wms.core.domain;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Date;
@ApiModel
public class BadLocationDetail implements Serializable {
private Long id;
@ApiModelProperty(value = "报残单号")
private String badOrderNo;
@ApiModelProperty(value = "货位号")
private String locationCode;
private String skuCode;
private String goodsModel;
private String goodsName;
private String goodsUnit;
@ApiModelProperty(value = "计划数量")
private BigDecimal quantity;
@ApiModelProperty(value = "实际数量")
private BigDecimal realQuantity;
@ApiModelProperty(value = "0:新建 10:进行中 20:已完成")
private Integer status;
@JsonFormat(locale="zh", timezone="GMT+8", pattern="yyyy-MM-dd HH:mm:ss")
private Date productionDate;
@ApiModelProperty(value = "效期")
private Double expiryDay;
@ApiModelProperty(value = "有效期至")
private Date periodDate;
@ApiModelProperty(value = "原因")
private String reason;
private String createUser;
private Date createTime;
private String updateUser;
private Date updateTime;
private Integer yn;
private static final long serialVersionUID = 1L;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getBadOrderNo() {
return badOrderNo;
}
public void setBadOrderNo(String badOrderNo) {
this.badOrderNo = badOrderNo;
}
public String getLocationCode() {
return locationCode;
}
public void setLocationCode(String locationCode) {
this.locationCode = locationCode;
}
public String getSkuCode() {
return skuCode;
}
public void setSkuCode(String skuCode) {
this.skuCode = skuCode;
}
public String getGoodsModel() {
return goodsModel;
}
public void setGoodsModel(String goodsModel) {
this.goodsModel = goodsModel;
}
public String getGoodsUnit() {
return goodsUnit;
}
public void setGoodsUnit(String goodsUnit) {
this.goodsUnit = goodsUnit;
}
public BigDecimal getQuantity() {
return quantity;
}
public void setQuantity(BigDecimal quantity) {
this.quantity = quantity;
}
public BigDecimal getRealQuantity() {
return realQuantity;
}
public void setRealQuantity(BigDecimal realQuantity) {
this.realQuantity = realQuantity;
}
public Integer getStatus() {
return status;
}
public void setStatus(Integer status) {
this.status = status;
}
public Date getProductionDate() {
return productionDate;
}
public void setProductionDate(Date productionDate) {
this.productionDate = productionDate;
}
public Double getExpiryDay() {
return expiryDay;
}
public void setExpiryDay(Double expiryDay) {
this.expiryDay = expiryDay;
}
public Date getPeriodDate() {
return periodDate;
}
public void setPeriodDate(Date periodDate) {
this.periodDate = periodDate;
}
public String getReason() {
return reason;
}
public void setReason(String reason) {
this.reason = reason;
}
public String getCreateUser() {
return createUser;
}
public void setCreateUser(String createUser) {
this.createUser = createUser;
}
public Date getCreateTime() {
return createTime;
}
public void setCreateTime(Date createTime) {
this.createTime = createTime;
}
public String getUpdateUser() {
return updateUser;
}
public void setUpdateUser(String updateUser) {
this.updateUser = updateUser;
}
public Date getUpdateTime() {
return updateTime;
}
public void setUpdateTime(Date updateTime) {
this.updateTime = updateTime;
}
public String getGoodsName() {
return goodsName;
}
public void setGoodsName(String goodsName) {
this.goodsName = goodsName;
}
public Integer getYn() {
return yn;
}
public void setYn(Integer yn) {
this.yn = yn;
}
}
效果图如下
重点
如果返回值是一个实体类型,一定要把返回对象用一个泛型对象封装起来。
启动项目,打开地址 http://localhost:8081/swagger-ui.html# 就可以看到效果