springboot整合swagger

特别说明：本次项目整合基于idea进行的，如果使用Eclipse可能操作会略有不同，不过总的来说不影响。

springboot整合之如何选择版本及项目搭建

springboot整合之版本号统一管理 

springboot整合mybatis-plus+durid数据库连接池

springboot整合swagger

springboot整合mybatis代码快速生成

springboot整合之统一结果返回

springboot整合之统一异常处理

springboot整合之logback日志配置

springboot整合pagehelper分页

springboot整合本地缓存

springboot整合redis + redisson

springboot整合elasticsearch

springboot整合rabbitMq

springboot整合canal实现缓存一致性

springboot整合springSecurity(前后端不分离版本)

在开始之前先说一下自己的理解。我觉得既然要使用，首先就要知道为什么要用？该不该用？如果说我们的项目就俩人开发的一个小项目，又没有前后端分离，而且有比较急着上线，那我觉得这种真是没有必要用swagger。这里只是举个例子，就是告诉大家没有必要为了swagger而swagger。

我认为swagger更适合前后端分离情况，或者需要协同开发给别人提供接口测试的时候使用。在这种情况下能够提高协同的效率。如果一项技术的引进不能提高开发效率，或者对项目本身没有什么提升，我觉得引入的意义就不大。而且引入很多没用的文件对内存也是影响，有时候甚至会影响我们程序的性能。

如果确定适合，那就整合进来。但是千万注意一点。这个只能是测试环境使用，千万不要放到正式环境。这个一定要注意！！！关于怎么设置正式环境不可用会在本次整合中给出示范。

我在项目开发中用过两种不同风格的swagger UI，这里会都展示一下，具体用那种大家可以根据需要来选择就好了。

一、pom文件引入

因为跟之前的几次的整合相比这次对版本进行了统一的依赖管理，所以直接贴上了所有的整合pom,如果有小伙伴是按照之前一步一步来的，这里直接替换pom就好了。

    4.0.0
    
    
        org.springframework.boot
        spring-boot-starter-parent
        2.3.12.RELEASE
    

    
    com.example
    springboot-demo
    0.0.1-SNAPSHOT
    springboot-demo
    springboot-demo

    
    
        8
        1.2.15
        3.4.2
        2.9.2
    


    
    
        
        
            org.springframework.boot
            spring-boot-starter
        

        
        
            org.springframework.boot
            spring-boot-starter-web
        

        
        
            org.springframework.boot
            spring-boot-devtools
            runtime
            true
        

        
        
            org.projectlombok
            lombok
            true
        

        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        

        
        
            mysql
            mysql-connector-java
        

        
        
            com.alibaba
            druid-spring-boot-starter
            ${druid.version}
        

        
        
            com.baomidou
            mybatis-plus-boot-starter
            ${mybatis-plus.version}
        

        
        
            io.springfox
            springfox-swagger2
            ${swagger.version}
        

        
            io.springfox
            springfox-swagger-ui
            ${swagger.version}
        

        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.9.6
        

    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok
                        
                    
                
            
        
    

二、创建swagger配置类

首先把位置说明一下

package com.example.springbootdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@Profile("dev")
public class SwaggerConfig {
	/**
	 * 创建API应用 apiInfo() 增加API相关信息
	 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
	 * 本例采用指定扫描的包路径来定义指定要建立API的目录。
	 */
	@Bean
	public Docket createRestApi() {

		return new Docket(DocumentationType.SWAGGER_2)
				//接口说明信息
				.apiInfo(apiInfo())
				// 选择那些路径和api会生成document
				.pathMapping("/").select()
				// 对所有api进行监控
				.apis(RequestHandlerSelectors.any())
				.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();
	}


	/**
	 * 创建该API的基本信息（这些基本信息会展现在文档页面中）
	 *
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("测试接口文档")
				.contact(new Contact("William","https://www.baidu.com","[email protected]"))
				.termsOfServiceUrl("https://www.baidu.com")
				.description("测试接口文档")
				.version("1.0")
				.build();
	}

}

说明：

@Configuration   将当前配置类交给spring管理
@EnableSwagger2  开启swagger注解，此注解也可以添加到spring boot启动类
@Profile("dev")  开启只有dev环境生效，此外swagger也提供了基于环境的可见性设置，这里就不作详细介绍了，如果感兴趣的可以自己研究一下，也很简单。

三、创建测试类

 因为测试，我们先临时写一个测试类，主要就是测试我们的swagger是否整合成功。

package com.example.springbootdemo.controller;

import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @description: TestController 

 * @date: 2022/12/17 0017 上午 10:06 

 * @author: William 

 * @version: 1.0 

 */
@Api(tags = "测试接口")
@RestController
@RequestMapping("test")
public class TestController {

    @Autowired
    private UserService userService;


    @ApiOperation("根据用户ID获取用户信息接口")
    @GetMapping("user/{id}")
    public String getUserById(@PathVariable("id") Integer id){
        //参数校验
        if(id == null || id<=0){
            return "参数非法";
        }
        User user = userService.getById(id);
        return user.toString();
    }

}

四、启动测试

首先给大家看一下我比较喜欢的一种，输入http://localhost:8080/doc.html进行访问

 各人觉得很不错的一个UI页面，看起来很舒服。而且支持离线导出，相当给力。个人觉得比swagger自带的UI要好用一点。

然后就是另一种：输入http://localhost:8080/swagger-ui.html

 这种是我们比较常见的。我以前也经常用，后来发现了第一种这种就没用了。

 OK，到这里整合就完成了。下面就是常用的一些注解了。

五、swagger常用注解 

从官方给的解释，各位学习使用的时候建议直接从这里看，而且都给了例子，很简单。

Name	Description
@Api	Marks a class as a Swagger resource.
@ApiImplicitParam	Represents a single parameter in an API Operation.
@ApiImplicitParams	A wrapper to allow a list of multiple ApiImplicitParam objects.
@ApiModel	Provides additional information about Swagger models.
@ApiModelProperty	Adds and manipulates data of a model property.
@ApiOperation	Describes an operation or typically a HTTP method against a specific path.
@ApiParam	Adds additional meta-data for operation parameters.
@ApiResponse	Describes a possible response of an operation.
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.
@Authorization	Declares an authorization scheme to be used on a resource or an operation.
@AuthorizationScope	Describes an OAuth2 authorization scope.

好了，到这里我们swagger就整合好了。另外说一下，为了展示两种效果所以我在pom中引入了两个swagger-ui的jar包，后面我会删掉一个，只保留一个。大家可以根据自己需要来。我觉得最好只保留一个就好了。

六、最终pom

我保留的是我比较喜欢的一个，修改以后的pom文件如下：如果跟我一样的可以直接复制到自己的项目。

    4.0.0
    
    
        org.springframework.boot
        spring-boot-starter-parent
        2.3.12.RELEASE
    

    
    com.example
    springboot-demo
    0.0.1-SNAPSHOT
    springboot-demo
    springboot-demo

    
    
        8
        1.2.15
        3.4.2
        2.9.2
        1.9.6
    



    
        
        
            org.springframework.boot
            spring-boot-starter
        

        
        
            org.springframework.boot
            spring-boot-starter-web
        

        
        
            org.springframework.boot
            spring-boot-devtools
            runtime
            true
        

        
        
            org.projectlombok
            lombok
            true
        

        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        

        
        
            mysql
            mysql-connector-java
        

        
        
            com.alibaba
            druid-spring-boot-starter
            ${druid.version}
        

        
        
            com.baomidou
            mybatis-plus-boot-starter
            ${mybatis-plus.version}
        

        
        
            io.springfox
            springfox-swagger2
            ${swagger.version}
        

        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            ${swagger-ui.version}
        

    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok