1. 简介:
Springboot 版本:2.4.0
Swagger 版本:3.0.0
knife4j 版本:2.0.7
2. 配置步骤:
- pom 配置:
<!-- swagger3-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- 防止进入swagger页面报类型转换错误,排除3.0.0中的引用,手动增加1.6.2版本 -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.6.2</version>
</dependency>
<!--knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.7</version>
</dependency>
2.SwaggerConfig 配置
package com.dechnic.tfoms.config;
import com.dechnic.tfoms.vo.ResultCode;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.beans.factory.annotation.Value;
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.builders.ResponseBuilder;
import springfox.documentation.service.*;
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.Arrays;
import java.util.List;
import static org.springframework.http.HttpMethod.*;
/**
* Swagger2的接口配置
*/
@EnableSwagger2
@EnableKnife4j
@Configuration
public class SwaggerConfig {
/**
* 是否开启swagger
*/
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 设置请求的统一前缀
*/
@Value("${swagger.pathMapping}")
private String pathMapping;
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
List<Response> responseList = new ArrayList<>();
Arrays.stream(ResultCode.values()).forEach(resultCode -> {
responseList.add(new ResponseBuilder().code(resultCode.getCode().toString()).description(resultCode.getMsg()).build());
});
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(enabled)
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
// .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
// 扫描所有
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
/* 设置安全模式,swagger可以设置访问token */
// .securitySchemes(securitySchemes())
// .securityContexts(securityContexts())
.pathMapping(pathMapping)
.globalResponses(GET, responseList)
.globalResponses(POST, responseList)
.globalResponses(PUT, responseList)
.globalResponses(DELETE, responseList);
}
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("标题:能耗接口文档")
// 描述
.description("描述:用于查询能耗")
// 作者信息
.contact(new Contact("", null, null))
// 版本
.version("版本号: ")
.build();
}
}
- ResultCode 通用返回代码
package com.dechnic.tfoms.vo;
import lombok.*;
/**
* @className: ResultCode
* @author: houqd
* @date: 2022/11/1
**/
@Getter
@AllArgsConstructor
@NoArgsConstructor
public enum ResultCode {
SUCCESS(1,"成功"),
ERROR(0,"失败"),
SERVER_ERROR(500,"服务器错误"),
UNLAWFUL(401,"无权限"),
PARAM_ERROR(405,"参数错误"),
NOT_LOGIN(406,"未登录");
private Integer code;
private String msg;
}
- OmsdcApiController 配置
package com.dechnic.tfoms.controller;/**
* @className: OmsdcApiController
* @author: houqd
* @date: 2022/10/31
**/
import com.dechnic.tfoms.mapper.VSMeterinstdatasMapper;
import com.dechnic.tfoms.service.IApiService;
import com.dechnic.tfoms.vo.*;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
*@description: 第三方能耗接口
*@author:houqd
*@time: 2022/10/31 18:11
*
*/
@Api("能耗接口")
@RequestMapping("/omsdc")
@RestController
public class OmsdcApiController {
@Autowired
private IApiService apiService;
@ApiOperation("获取表实时数据接口")
@PostMapping(value = "/getMeterInstDatas",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public JsonVo getMeterInstDatas( @RequestBody(required = false) MeterInstDatasVo meterInstDatasVo){
List<MeterInstDatasResult> meterInstDatasResults = apiService.searchMeterInstDatas(meterInstDatasVo);
return JsonVo.success(meterInstDatasResults);
}
@ApiOperation("支路日数据接口")
@PostMapping(value = "/searchServiceDayResult",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public JsonVo searchServiceDayResult(@RequestBody(required = false) ServiceDayResultVo serviceDayResultVo){
List<ServiceDayResultResult> serviceDayResultResults = apiService.searchServiceDayResult(serviceDayResultVo);
return JsonVo.success(serviceDayResultResults);
}
@ApiOperation("支路月数据接口")
@PostMapping(value = "/searchServiceMonthResult", consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public JsonVo searchServiceMonthResult(@RequestBody(required = false) ServiceMonthResultVo serviceMonthResultVo){
List<ServiceMonthResultResult> serviceMonthResultResults = apiService.searchServiceMonthResult(serviceMonthResultVo);
return JsonVo.success(serviceMonthResultResults);
}
}
- yml 配置
# Swagger配置
swagger:
# 是否开启swagger
enabled: true
# 请求前缀
pathMapping: /
- 展示界面: