访问:http://localhost:9999/doc.html
1. maven依赖
<!--swagger3 start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<!--swagger3 end-->
2. yml中配置
spring:
profiles:
active: dev
#主要是这
mvc:
pathmatch:
matching-strategy: ant_path_matcher
3. 创建swagger配置类
package com.wang.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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableOpenApi // swagger3开启注解,与swagger2不同
public class Swagger3Config {
/**
* 全局通用属性(摘要)配置
*/
@Bean
public Docket createRestApi() {
//主页
return new Docket(DocumentationType.OAS_30)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("接口文档")
.description("暂无")
.version("1.0")
.contact(new Contact("wang", "wang-url", "xxxxx@.com"))
.license("接口文档1.0")
.licenseUrl("http://www.baidu.com")
.build()).securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* 项目通用参数,添加全局参数——登录认证token(若无可省略)
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
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;
}
}
4. WebMvcConfig配置
package com.wang.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
}
}
5. 接口测试
@RestController
@RequestMapping("/test")
@Api(value = "测试接口", tags = {"测试接口"})
public class TestController {
@ApiOperation("测试ok方法")
@GetMapping("/ok")
public String cc(){
return "okok";
}
}
效果展示
6. 生产环境禁用(但我不喜欢用)
/**
* swagger文档
*
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${swagger.enable}")
private boolean enable = false;
@Bean
public Docket docket() {
ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name(TokenFilter.TOKEN_KEY)//接口默认token参数
.description("header参数")
.required(false)
.modelRef(new ModelRef("string")); // 在swagger里显示header
return new Docket(DocumentationType.SWAGGER_2).groupName("微服务接口调用文档")
.enable(enable)
.apiInfo(new ApiInfoBuilder().title("微服务接口调用文档")
.contact(new Contact("xx", "", "xxxx@qq.com")).version("1.1").build())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select().paths(PathSelectors.any()).build();
}
}
默认配置swagger为关闭
application.yml配置:
swagger:
enable: false
只在dev环境中开启,其他环境不配置
swagger:
enable: true
这样配置之后只有开发环境中开启了swagger,其他环境默认关闭。