spring boot 集成 swagger

绝地灬酷狼 2022-04-25 06:22 204阅读 0赞

swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。

在pom.xml中引入依赖

<dependency>
    		    <groupId>io.springfox</groupId>
    		    <artifactId>springfox-swagger2</artifactId>
    		    <version>2.9.2</version>
    		</dependency>
    		
    		
    		<dependency>
    		    <groupId>io.springfox</groupId>
    		    <artifactId>springfox-swagger-ui</artifactId>
    		    <version>2.9.2</version>
    		</dependency>
    		<dependency>
    		    <groupId>io.swagger</groupId>
    		    <artifactId>swagger-annotations</artifactId>
    		    <version>1.5.21</version>
    		</dependency>
    		<dependency>
    		    <groupId>io.swagger</groupId>
    		    <artifactId>swagger-models</artifactId>
    		    <version>1.5.21</version>
    		</dependency>

配置 swagger

@Configuration
    @EnableSwagger2
    @ConditionalOnExpression("${swagger.enable:true}")
    public class SwaggerConfig {
    
        @Bean
        public Docket createDocket(){
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(new ApiInfoBuilder().title("接口API")
                            .description("相关接口API文档")
                            .version("1.1").build())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.changdao"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
    
    }

[swagger官网][swagger]  
swagger 注解：

@Api：用在请求的类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
    
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
    
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
                （这种一般用在post创建的时候，使用@RequestBody这样的场景，
                请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：用在属性上，描述响应类的属性

效果图：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjExODI4NA_size_16_color_FFFFFF_t_70]  
测试的时候可以在拦截器先屏蔽swagger

@Override
    	public void addInterceptors(InterceptorRegistry registry) {
            registry.addInterceptor(new ApiInterceptor())
            .addPathPatterns("/**")
            .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")
            .excludePathPatterns("/user/login");
    		super.addInterceptors(registry);
    	}
    	
    	@Override
    	public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }

[swagger]: https://swagger.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjExODI4NA_size_16_color_FFFFFF_t_70]: /images/20220205/a79b2b2f68654523923314c1e5ad20b7.png