1.引入swagger3.0相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.创建swagger配置类
@Configuration
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
//资源
.globalResponses(HttpMethod.GET, new ArrayList<>())
.globalResponses(HttpMethod.PUT, new ArrayList<>())
.globalResponses(HttpMethod.POST, new ArrayList<>())
.globalResponses(HttpMethod.DELETE, new ArrayList<>())
//是否启动
.enable(true)
//头部信息
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
//过滤某个路径
.paths(PathSelectors.any())
.build()
//协议
.protocols(newHashSet("https", "http"))
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("@author LiuYong")
.contact(new Contact("LiuYong", null, "liuyong1450@163.com"))
.version("1.0")
.build();
}
/**
* 设置接口单独的授权信息
*/
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "header"));
}
/**
* 授权信息全局应用
*/
private List<SecurityContext> securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(
Collections.singletonList(new SecurityReference("BASE_TOKEN",
new AuthorizationScope[]{new AuthorizationScope("global", "")}
)))
//.forPaths(PathSelectors.any())
.build()
);
}
@SafeVarargs
private final <T> Set<T> newHashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
}
3.创建swagger资源类
@Component
@Primary
public class SwaggerProvider implements SwaggerResourcesProvider {
@Autowired
private RouteLocator routeLocator;
/**
* 网关应用名称
*/
@Value("${spring.application.name}")
private String self;
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
List<String> routeHosts = new ArrayList<>();
routeLocator.getRoutes()
.filter(route -> route.getUri().getHost() != null)
.filter(route -> Objects.equals(route.getUri().getScheme(), "lb"))
//过滤掉网关自身的服务 uri中的host就是服务id
.filter(route -> !self.equalsIgnoreCase(route.getUri().getHost()))
.subscribe(route -> routeHosts.add(route.getUri().getHost()));
// 记录已经添加过的server,存在同一个应用注册了多个服务在注册中心上
Set<String> set = new HashSet<>();
routeHosts.forEach(instance -> {
// 拼接url ,请求swagger的url
String url = "/" + instance.toLowerCase() + CommonConstant.SWAGGER2URL;
if (!set.contains(url)) {
set.add(url);
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setUrl(url);
swaggerResource.setName(instance);
resources.add(swaggerResource);
}
});
return resources;
}
}
注意事项:
- swagger3默认的url后缀 : SWAGGER2URL = "/v3/api-docs"
4.添加注解
- @EnableOpenApi:启动类上添加此注解,使swagger生效
- @Api:类上添加此注解,注明此类的功能
- @ApiOperation:方法上添加此注解,注明此方法的功能
5.添加swagger插件注解
<!-- swagger插件 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
6.访问swagger3.0文档
- 访问地址:ip:port/doc.html