Swagger-springFox3.0使用教程

Swagger-springfox 3.0部署

1.依赖

<!--Swagger-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

2.配置类

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.ArrayList;
import java.util.List;

/**
 * swagger2配置
 * @author huang cheng
 * 2021/8/13
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    private final static String groupName = "cheng";//组群名称

    private final static String headerName = "Authorization";//需要swagger每次调接口前携带的头信息的key
    //private final static String headerName2 = "test";//如果要多个请求头信息，自行解放注释

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//文档信息
                .groupName(groupName)//组群名称
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cheng.authonlytoken.controller"))//需要扫描的api所在目录
                .paths(PathSelectors.any())//匹配全部地址路径
                .build()
                .securitySchemes(securitySchemes())//配置安全方案
                .securityContexts(securityContexts())//配置安全方案所实现的上下文
                ;
    }

    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<>();
        //配置header头1
        ApiKey token_access = new ApiKey(headerName, headerName, "header");
        apiKeyList.add(token_access);
        //配置header头2
        //ApiKey token_access2 = new ApiKey( headerName2, headerName2, "header");
        //apiKeyList.add(token_access2);
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContextList = new ArrayList<>();
        List<SecurityReference> securityReferenceList = new ArrayList<>();
        //为每个api添加请求头
        securityReferenceList.add(new SecurityReference(headerName, scopes()));
        //以此类推
        //securityReferenceList.add(new SecurityReference(headerName2, scopes()));
        securityContextList.add(SecurityContext
                .builder()
                .securityReferences(securityReferenceList)
                .forPaths(PathSelectors.any())
                .build()
        );
        return securityContextList;
    }

    private AuthorizationScope[] scopes() {
        return new AuthorizationScope[]{new AuthorizationScope("global", "accessAnything")};//作用域为全局
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger2文档")
                .description("更多精彩博客请关注：https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343")
                .termsOfServiceUrl("https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343")
                .contact(new Contact("cheng", "https://blog.csdn.net/qq_42495847?spm=1000.2115.3001.5343", "1003816735@qq.com"))
                .version("1.0")
                .build();
    }

}

• ApiKey是对请求的header进行设置，第一、二个参数是header的key，第三个参数是用户输入

3.常用注解

SpringFox基于swagger2

swagger2	swagger3	注解位置
@Api(tags = “接口类描述”)	@Tag(tags = “接口类描述”)	Controller 类上
@ApiOperation(“接口方法描述”)	@Operation(summary =“接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上 @Parameters 里
@ApiParam(“参数描述”)	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel(description = “dto类描述”)	@Schema(description = “dto类描述”)	DTO类上
@ApiModelProperty(“属性描述”)	@Schema(description = “属性描述”)	DTO属性上

4.实体类

@ApiModel("用户信息")
@Data
public class UserInfo {
    @ApiModelProperty("用户id")
    private String id;
    @ApiModelProperty("用户名")
    private String username;
}

5.统一返回类

/**
 * 通用返回类型
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class CResponse<T> implements Serializable {

    private static final long serialVersionUID = 1L;
    private String code;//状态码
    private String message;//文字描述
    private T data;//数据

    public CResponse(String code, String message) {
        this(code,message,null);
    }

}

6.控制层

@Api(tags="登录管理")
@RestController
@RequestMapping("/auth")
public class LoginController {

    @Resource
    private LoginService loginService;

    @ApiOperation("得到当前token中包含的用户信息")
    @PostMapping("/getUserInfo")
    public CResponse<UserInfo> getUserInfo(@RequestHeader("Authorization") String token){
        return loginService.getUserInfo(token);
    }
}

7.控制器放行地址

如果有spring-Security或者拦截器过滤器之类的配置，需要对以下地址进行放行

    /**
     * 放行Swagger
     */
    public static final String[] SWAGGER_WHITELIST = {
            "/swagger-ui.html",
            "/swagger-ui/**",
            "/swagger-resources/**",
            "/v2/api-docs",
            "/v3/api-docs",
            "/v3/api-docs/swagger-config",
            "/webjars/**",
            "/doc.html",
    };

8.启动

访问localhost:8080/swagger-ui/index.html

基本功能就ok了

深度功能请访问官网文档：SpringFox文档