Swagger 3.0配置整合使用教程

怼烎@ 2022-12-15 14:21 750阅读 0赞

##### ▌swagger介绍 #####

> Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者。  
> 对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证API 文档的及时性将有很大的帮助。  
>   
> swagger2于17年停止维护，现在最新的版本为17年发布的 Swagger3（Open Api3）。

##### ▌springfox介绍 #####

> SpringFox是 spring 社区维护的一个项目（非官方）  
> 由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从这个组件发展而来。

##### ▌springfox-swagger 2 #####

SpringBoot项目整合swagger2需要用到两个依赖：`springfox-swagger2`和`springfox-swagger-ui`，用于自动生成swagger文档。

*  springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
 *  springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

#### ▌SpringFox 3.0.0 发布 ####

##### 此版本的亮点： #####

*  Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
 *  Spring Integration支持。
 *  SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
 *  支持OpenApi 3.0.3。
 *  零依赖。几乎只需要spring-plugin，[swagger-core][] ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

##### 兼容性说明： #####

*  需要Java 8
 *  需要Spring5.x（未在早期版本中测试）
 *  需要SpringBoot 2.2+（未在早期版本中测试）

--------------------

### ▌swagger3.0 与2.xx配置差异： ###

1.  应用主类添加注解`@EnableOpenApi` (swagger2是@EnableSwagger2)
2.  swagger配置类`SwaggerProperties.class`，与swagger2.xx 版本有差异，具体看下文
3.  自定义一个配置类 `SwaggerConfiguration.class`,看下文
4.  访问地址：`http://localhost:8080/swagger-ui/index.html` (swagger2.xx版本访问的地址为http://localhost:8080/swagger-ui.html)

### ▌整合使用完整过程 ###

Maven项目中引入springfox-boot-starter依赖：

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

application.yml配置

spring:
      application:
        name: springfox-swagger
    server:
      port: 8080
    # ===== 自定义swagger配置 ===== #
    swagger:
      enable: true
      application-name: ${ spring.application.name}
      application-version: 1.0
      application-description: springfox swagger 3.0整合Demo
      try-host: http://localhost:${server.port}

#### 应用主类 Controller类 ####

@EnableOpenApi // 也可以不写此注解
    @Api(description="讲师管理")
    @RestController
    @RequestMapping("/admin/edu/teacher")
    
    public class MyController { 
    
        @Autowired
        private TeacherService teacherService;
        
        @ApiOperation(value = "所有讲师列表")
        @GetMapping
        public List<Teacher> list(){ 
            return teacherService.list(null);
        }
        
        @ApiOperation(value = "根据ID删除讲师")
        @DeleteMapping("{id}")
        public boolean removeById(
                @ApiParam(name = "id", value = "讲师ID", required = true)
                @PathVariable String id){ 
            return teacherService.removeById(id);
        }
    }

一些常用注解说明

> @Api：用在controller类，描述API接口  
> @ApiOperation：描述接口方法  
> @ApiModel：描述对象  
> @ApiModelProperty：描述对象属性  
> @ApiImplicitParams：描述接口参数  
> @ApiResponses：描述接口响应  
> @ApiIgnore：忽略接口方法

#### 自定义一个swagger配置类`SwaggerProperties.class` ####

@Component
    @ConfigurationProperties("swagger")
    public class SwaggerProperties { 
        /** * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量 */
        private Boolean enable;
        
        /** * 项目应用名 */
        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;
        }
    }

#### springfox swagger3配置类`SwaggerConfiguration.class`： ####

import io.swagger.models.auth.In;
    import org.apache.commons.lang3.reflect.FieldUtils;
    import org.springframework.boot.SpringBootVersion;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.util.ReflectionUtils;
    import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
    import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    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.lang.reflect.Field;
    import java.util.*;
    
    @Configuration
    public class SwaggerConfiguration implements WebMvcConfigurer { 
        private final SwaggerProperties swaggerProperties;
    
        public SwaggerConfiguration(SwaggerProperties swaggerProperties) { 
            this.swaggerProperties = swaggerProperties;
        }
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.OAS_30).pathMapping("/")
    
                    // 定义是否开启swagger，false为关闭，可以通过变量控制
                    .enable(swaggerProperties.getEnable())
    
                    // 将api的元信息设置为包含在json ResourceListing响应中。 
                    .apiInfo(apiInfo())
    
                    // 接口调试地址
                    .host(swaggerProperties.getTryHost())
    
                    // 选择哪些接口作为swagger的doc发布
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build()
    
                    // 支持的通讯协议集合
                    .protocols(newHashSet("https", "http"))
    
                    // 授权信息设置，必要的header token等认证信息
                    .securitySchemes(securitySchemes())
    
                    // 授权信息全局应用
                    .securityContexts(securityContexts());
        }
    
        /** * API 页面上半部分展示信息 */
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
                    .description(swaggerProperties.getApplicationDescription())
                    .contact(new Contact("lighter", null, "123456@gmail.com"))
                    .version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
                    .build();
        }
    
        /** * 设置授权信息 */
        private List<SecurityScheme> securitySchemes() { 
            ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
            return Collections.singletonList(apiKey);
        }
    
        /** * 授权信息全局应用 */
        private List<SecurityContext> securityContexts() { 
            return Collections.singletonList(
                    SecurityContext.builder()
                            .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{ new AuthorizationScope("global", "")})))
                            .build()
            );
        }
    
        @SafeVarargs
        private final <T> Set<T> newHashSet(T... ts) { 
            if (ts.length > 0) { 
                return new LinkedHashSet<>(Arrays.asList(ts));
            }
            return null;
        }
    
        /** * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息 */
        @SuppressWarnings("unchecked")
        @Override
        public void addInterceptors(InterceptorRegistry registry) { 
            try { 
                Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
                List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
                if (registrations != null) { 
                    for (InterceptorRegistration interceptorRegistration : registrations) { 
                        interceptorRegistration
                                .excludePathPatterns("/swagger**/**")
                                .excludePathPatterns("/webjars/**")
                                .excludePathPatterns("/v3/**")
                                .excludePathPatterns("/doc.html");
                    }
                }
            } catch (Exception e) { 
                e.printStackTrace();
            }
        }
    
    }

效果图：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDIwMzE1OA_size_16_color_FFFFFF_t_70_pic_center]

##### ▌扩展资料 #####

swagger 官网：swagger.io([https://swagger.io/][https_swagger.io])  
springfox 官网：springfox([http://springfox.github.io/springfox/][http_springfox.github.io_springfox])  
springfox Github 仓库：springfox / springfox([https://github.com/springfox/springfox][https_github.com_springfox_springfox])  
springfox-demos Github 仓库：springfox / springfox-demos([https://github.com/springfox/springfox-demos][https_github.com_springfox_springfox-demos])  
springfox Maven 仓库：Home » io.springfox([https://mvnrepository.com/artifact/io.springfox][https_mvnrepository.com_artifact_io.springfox])

--------------------

![在这里插入图片描述][20201122200824866.gif_pic_center]

[swagger-core]: https://github.com/swagger-api/swagger-core
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDIwMzE1OA_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/9e7563a3101e479db066c8c6e5a4600a.png
[https_swagger.io]: https://swagger.io/
[http_springfox.github.io_springfox]: http://springfox.github.io/springfox/
[https_github.com_springfox_springfox]: https://github.com/springfox/springfox
[https_github.com_springfox_springfox-demos]: https://github.com/springfox/springfox-demos
[https_mvnrepository.com_artifact_io.springfox]: https://mvnrepository.com/artifact/io.springfox
[20201122200824866.gif_pic_center]: /images/20221123/72411c90240d46f18370c0d4e5a9f777.png