本文共 3786 字，大约阅读时间需要 12 分钟。

Springfox Swagger 2.x 安装与配置实例

在 Spring Boot 项目中集成 Swagger 以便文档化 API，这是一个强大的工具。以下是详细的配置步骤，帮助您快速上手。

一、安装依赖

首先，我们需要将 Swagger 和 Swagger-UI 显示添加到项目依赖中：

       
    
     io.swagger
        
    
     springfox-swagger2
        
    
     2.9.2
    
   
       
    
     io.swagger
        
    
     swagger-ui
        
    
     2.9.2
    
   

确保通过 MavenResolver 或相关 Package Repository 获取最新版本。

二、配置 Swagger 文档

为了创建 Swagger 文档，我们需要一个配置类，通常放在 config 包中。

1. 创建 SwaggerConfig 类

import io.swagger.annotations.ApiInfo;import io.swagger.service.ApiInfoBuilder;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import io.swagger.service.ModelRef;import io.swagger.service.Parameter;@ApiInfo(    title = "项目文档示例",    description = "这是一个简单的 API 文档示例",    version = "1.0")@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket api() {        ParameterBuilder parameterBuilder = new ParameterBuilder()            .name("token")            .description("token")            .modelRef(new ModelRef("string"))            .parameterType("header")            .required(false)            .build();        Parameter parameter = parameterBuilder.build();        return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())            .select()            .apis(RequestHandlerSelectors.any())            .paths(PathSelectors.any())            .build()            .globalOperationParameters(Collections.singletonList(parameter));    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()            .title("项目文档示例")            .description("这是一个简单的 API 文档示例 1.0")            .termsOfServiceUrl("https://github.com")            .version("1.0")            .build();    }}

2. 配置ApiController

在每个 @RestController 上加入 @Api 注解，可以添加描述和标签。

@RestController@RequestMapping("/api")@Api(tags = "关于测试")public class TestController {    @GetMapping("/test")    @ApiOperation(value = "测试函数")    void test() {        // TODO: 实现逻辑    }}

三、处理拦截器并允许 Swagger

为了确保 Swagger UI 能够正常运行，需要放行相关路径：

import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.InterceptorRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Configurationpublic class WebConfig implements WebMvcConfigurer {    private TokenHelper tokenHelper;    @Override    public void addInterceptors(InterceptorRegistry registry) {        registry.addInterceptor(new TokenInterceptor(tokenHelper))            .addPathPatterns("/**")            .excludePathPatterns("/api/generateToken", "/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");    }}

查看效果

重新启动项目后，访问 http://localhost:8080/swagger-ui.html 即可查看 Swagger 文档。

接口过滤

有些接口需要隐藏，可以在方法上添加 @ApiIgnore 注解。

@RestControllerpublic class LogDebugEnabled {    @GetMapping("/api/logdebug")    @ApiIgnore    void logdebug(@RequestParam String aa, @RequestParam String bb) {        logger.debug("这是 /api/logdebug 接口");        logger.debug("aa:{}", aa);        logger.debug("bb:{}", bb);    }}

实体描述

使用 @ApiModel 和 @ApiModelProperty 注解对 API 中的对象进行描述：

@ApiModel(description = "用户信息")class UserProfile {    @ApiModelProperty(nickname = "用户名", example = "example")    private String username;    @ApiModelProperty(nickname = "密码", example = "examplepass")    private String password;}

以上配置和文档示例已完成，您应该能够轻松集成并使用 Swagger 文档功能进行 API 文档化。

转载地址：http://nfkrz.baihongyu.com/