Swagger-API文档
Swagger
配置
导包
3.0.0以下版本maven导入依赖：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.version}</version>
</dependency>
3.0.0及以上版本可使用maven导入依赖：
Swagger API文档
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
编写配置类
配置类
package com.zsl.config.swagger;
import com.google.common.collect.Lists;
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.*;
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.Collections;
import java.util.List;
/**
* @Author zsl
* @Date 2022/1/21 11:16
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private final SwaggerProperties swaggerProperties;
public SwaggerConfig(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public Docket petApi() {
return new Docket(DocumentationType.SWAGGER_2)
// api文档信息
.apiInfo(apiInfo())
// 分组名称
.groupName(swaggerProperties.getApplicationVersion())
// 定义是否开启swagger,false为关闭，可以通过yaml配置变量控制
.enable(swaggerProperties.getEnable())
// 选择那些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.basePackage("com.zsl.controller")) // api路径
.paths(PathSelectors.any()) // 路径匹配
.build()
// 授权信息全局应用
.securityContexts(securityContexts())
// 授权信息设置，必要的header token等认证信息
.securitySchemes(apiKeys());
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(swaggerProperties.getApplicationName() + " 登录模块")
.description(swaggerProperties.getApplicationDescription())
.version("Application Version: " + swaggerProperties.getApplicationVersion())
.build();
}
/**
* 设置授权信息
*/
private List<SecurityScheme> apiKeys() {
return Lists.newArrayList(new ApiKey("Bearer Token", "Authorization", "header"));
}
/**
* 授权信息全局应用
*/
private List<SecurityContext> securityContexts() {
return Lists.newArrayList(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/.*"))
.build());
}
/**
*
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Collections.singletonList(new SecurityReference("Bearer Token", authorizationScopes));
}
}
资源类
package com.zsl.config.swagger;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
/**
* @Author zsl
* @Date 2022/1/23 14:40
*/
@Component
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {
private Boolean enable; // 是否开启swagger
private String applicationName; // 应用程序名称
private String applicationVersion; // 应用程序版本
private String applicationDescription; // 应用程序描述
private String tryHost; // 接口调试地址
public Boolean getEnable() {
return enable;
}
public void setEnable(Boolean enable) {
this.enable = enable;
}
public String getApplicationName() {
return applicationName;
}
public void setApplicationName(String applicationName) {
this.applicationName = applicationName;
}
public String getApplicationVersion() {
return applicationVersion;
}
public void setApplicationVersion(String applicationVersion) {
this.applicationVersion = applicationVersion;
}
public String getApplicationDescription() {
return applicationDescription;
}
public void setApplicationDescription(String applicationDescription) {
this.applicationDescription = applicationDescription;
}
public String getTryHost() {
return tryHost;
}
public void setTryHost(String tryHost) {
this.tryHost = tryHost;
}
}
yaml
# ===== 自定义swagger配置 ===== #
swagger:
enable: true
try-host: http://localhost:${server.port}
application-name: ${spring.application.name}
application-description: 登录练习 整合swagger 2.9.2
application-version: v0.0.1
注解
@Api
用在controller类，描述API接口
@ApiOperation
描述接口方法
@ApiModel
描述对象
@ApiModelProperty
描述对象属性
@ApiImplicitParams
描述接口参数
@ApiResponses
描述接口响应
@ApiIgnore
忽略接口方法
swagger-ui
3以下版本
url：http://:/swagger-ui.html
3及以上版本
url：http://:/swagger-ui/index.html