目录
依赖
常用注解
配置类和配置文件
Nginx配置
访问路径
效果展示
一些可能的问题
依赖
常用注解
@Tag：标识Controller
@Operation：标识方法
@Schema：标识字段
常用三个注解，其他不再赘述，请自行百度。
配置类和配置文件
@EnableOpenApi
@Configuration
@EnableKnife4j
public class Swagger3Config {
//服务名称
@Value("${swagger3.name}")
private String name;
//开关
@Value("${swagger3.enable}")
private Boolean enable;
//版本
@Value("${swagger3.version}")
private String version;
//描述
@Value("${swagger3.description}")
private String description;
//分组
@Value("${swagger3.group}")
private String group;
//扫描路径
@Value("${swagger3.selector}")
private String selector;
@Bean
public Docket docketForCommon(Environment environment) {
// 如果没有配置开关 那么开发测试环境打开、正式环境关闭
if (enable == null){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//判断当前环境是否为开发测试环境
enable = environment.acceptsProfiles(profiles);
}
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())//文档基础信息
//整合请求头authorization 原生页面传参时需要手动去掉Bearer
.securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER
.name("Authorization")//页面展示字段
.build()))
.securityContexts(Collections.singletonList(SecurityContext.builder()
.securityReferences(Collections.singletonList(SecurityReference.builder()
.scopes(new AuthorizationScope[0])
.reference("Authorization")
.build()))
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))// 声明作用域
.build()))
.groupName(group)// 分组信息 多人开发注册多个bean
.enable(enable)// 是否启用
.select()
//.withClassAnnotation(RestController.class)表示扫描类上有@RestController注解的类上接口
//.withMethodAnnotation(GetMappering)扫描GetMappering方法接口
.apis(RequestHandlerSelectors.basePackage(selector))// .basePackage()扫描指定路径下的所有接口 .any() 全扫描 .none() 全不扫描
.paths(PathSelectors.any())//路径过滤
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(name)//标题
.description(description)//描述
.version(version)//版本
.build();
}
# swagger3配置
swagger3:
# 服务名称
name: test
# 是否启动
enable: true
# 项目版本
version: v1.0.0
# 文档描述
description: Test说明文档
# 分组信息
group: common
# 扫描路径
selector: com.test.testController
Nginx配置
其中：
/v3、/swagger-resources、/swagger-ui、/swagger-ui/index.html为原生Swagger3需要请求的路径/资源。
/webjars、/favicon.ico/、/doc.html为knief4j美化需要请求的路径/资源。
proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port;
暴露端口和ip，提供给swagger3进行测试请求。
location ~* ^(/v3|/swagger-resources|/swagger-ui|/swagger-ui/index.html|/webjars/|/favicon.ico/|/doc.html) {
proxy_redirect off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://yourserver;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
}
upstream yourserver{
server ip:port;
}
访问路径
原生url（本地）：http://localhost:port/swagger-ui/index.html原生 url（线上）：https://ip:port/swagger-ui/index.html （nginx代理 必须要用https）Knife4j url（本地）: http://localhost:port/doc.htmlKnife4j url（线上）：https://ip:port/doc.html （nginx代理 必须要用https）
效果展示
原生：
knief4j：
一些可能的问题
项目内如jwt之类的鉴权功能记得放行。
if (requestURI.startsWith("/swagger")||requestURI.startsWith("/v3")||requestURI.startsWith("/webjars")||requestURI.startsWith("/favicon")
||requestURI.startsWith("/doc")||excludeUrls.contains(requestURI)) {
//Swagger放行
filterChain.doFilter(request, response);
}
好文链接
发表评论