SpringBoot整合Swagger2接口文档

Love The Way You Lie 2023-10-06 22:06 17阅读 0赞

### 一、添加依赖 ###

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

### 二、添加配置 ###

在我们的application.yaml 添加配置

swagger:
      title: xxx项目RESTful API
      description: 开发人员太懒，没有写描述
      version: 1.0
      contactName: lxt
      contactEmail:
      contactUrl:
      basePackageRest: com.qcby.xxx.rest
      termsOfServiceUrl:

在我们的config配置包下添加SwaggerProperties.java文件

@Component
    @ConfigurationProperties(prefix = "swagger")
    @Data
    public class SwaggerProperties {
        private String title;
        private String contactName;
        private String contactUrl;
        private String contactEmail;
        private String version;
        private String description;
        private String basePackageRest;
        private String termsOfServiceUrl;
    
    }

再建立SwaggerConfig.java

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Autowired
        private SwaggerProperties swaggerProperties;
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("REST接口8000")
                    .apiInfo(apiInfo())
                    .select()
                    //  配置自动扫描那些包下类型生成接口文档
                    .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackageRest()))
                    .build();
        }
        //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title(swaggerProperties.getTitle())
                    //创建人
                    .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(),swaggerProperties.getContactEmail()))
                    //版本号
                    .version(swaggerProperties.getVersion())
                    //描述
                    .description(swaggerProperties.getDescription())
                    .build();
        }
    }

另外其他类中的**注解**加方法

//  controller类
    @Api(value = "通用接口", tags = {"通用接口"})
    
    
    // 方法
    @ApiOperation("演示接口")
    
    // 参数
    @ApiImplicitParams(
        {@ApiImplicitParam(name = "Authorization", 
            value = "Authorization token", required = true, 
            dataType = "string", paramType = "header")}
            )
    // 实体类  
    @ApiModel("用户实体")       
    // 实体类字段
    @ApiModelProperty(value = "创建时间")

**拦截器不拦截接口文档（拦截则需要登录后可以登录）**

**如果需要不登陆即可访问，才需要配置（可选）**

@Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor()).addPathPatterns("/**")
                // 那些路径不拦截
                .excludePathPatterns("/login/**","/error"
                ,"/swagger-ui.html/**","/swagger-resources/**");
    }

### 三、测试 ###

接口文档地址：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Y-r5oiR6ICB5Lyv_size_20_color_FFFFFF_t_70_g_se_x_16][]

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Y-r5oiR6ICB5Lyv_size_20_color_FFFFFF_t_70_g_se_x_16 1][]

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Y-r5oiR6ICB5Lyv_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/a08d2fca4a10422e996a8eec2c1c7b7e.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5Y-r5oiR6ICB5Lyv,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5Y-r5oiR6ICB5Lyv_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/808ef95f56af4daf90340a271922f746.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5Y-r5oiR6ICB5Lyv,size_20,color_FFFFFF,t_70,g_se,x_16