springboot集成swagger

首先新建一个springboot项目和简单的CRUD接口，这里不做介绍，

下边直接介绍给一个开发中springboot项目配置swagger在线文档：

上代码：

1.在项目的api(controller)同级路径新建一个config包和Swagger2Config的配置类：

如下图：

Swagger2Config代码如下：

package ************.config;

import java.text.SimpleDateFormat;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 * @author super wang
 * @date 2021/02/22
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket productApi() {
        Predicate<RequestHandler> predicate = new Predicate<RequestHandler>() {
            @Override
            public boolean apply(RequestHandler input) {
                if (input.isAnnotatedWith(ApiOperation.class)) { //只有添加了ApiOperation注解的method才在API中显示 
                    Optional<ApiOperation> optional = input.findAnnotation(ApiOperation.class);
                    if(!optional.get().hidden()) {
                        return true;
                    }
                }
                return false;
            }
        };
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(predicate)
                .apis(RequestHandlerSelectors.basePackage("com.****API包路径****.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("===========文档标题名称可以是项目名==========").description("==========文档描述自己随便起==========").version("1.0.0")
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
        ObjectMapper objectMapper = new ObjectMapper();
        /**
         * 序列换成json时,将所有的long变成string
         * 因为js中得数字类型不能包含所有的java long值
         */
        SimpleModule simpleModule = new SimpleModule();
        simpleModule.addSerializer(Long.class, ToStringSerializer.instance);
        simpleModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
        objectMapper.registerModule(simpleModule);
        objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        jackson2HttpMessageConverter.setObjectMapper(objectMapper);
        converters.add(jackson2HttpMessageConverter);
    }
    
}

配置里需要改一下API包路径、文档标题和文档描述，最好和当前项目名称一致自行命名好了。

2.在项目的pom.xml文件中添加依赖：

 <!--swagger 依赖-->
        <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>

保存后更新一下maven依赖

idea操作如下：右键项目 => maven => Reload project 

3.在项目启动类上添加注解使文档生效：

@EnableSwagger2

import springfox.documentation.swagger2.annotations.EnableSwagger2;

4.完成上述步骤所有配置就结束了。但是想要浏览器访问在线文档，还需要在API接口上添加相应的注解才行

步骤如下：

      1.找到一个写好的接口API ，加上注解（tags为接口分组）

@Api(value = "API接口-文件上传", tags = "27 文件上传")

      

     2.找到需要的方法，加上注解

@ApiOperation(value = "27.01 通用文件上传", notes = "通用文件上传")
@PostMapping("/saveFilesUpload")

   3.找到方法的入参对象加上注解

@ApiModel(value = "接收对象", description="接收对象")

  如果入参对象属性和数据库字段存在映射关系，加上注解

@TableName("table_name")

  普通属性字段需要文档查看到，加注解（和默认值）

@ApiModelProperty(value = "属性名称", example = "文档默认值")

   如果对象和数据库存在映射关系，已添加 对象属性包含对数据库不存在的属性值，在属性上加注解

@TableField(exist = false)

   时间类型的属性，需要另外添加格式化注解

@com.fasterxml.jackson.annotation.JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")

另外：如果参数属性有非空校验需要注意，以String类为例：加注解@NotNull 、@NotBlank (两者区别自行百度)

    @ApiModelProperty(value = "备注（必填）", example = "TYPE_01")
    @NotNull(message = "类型不能为空", groups = {Insert.class})
    @NotBlank(message = "类型不能为空", groups = {Insert.class})
    private String type;

 想要非空校验生效还需要在方法参数栏，添加注解 @Validated

注意：@ApiOperation 注解的 hidden = false 表示接口是否在文档中隐藏，默认false为不显示

例：

    @ApiOperation(value = "更新文件数据", notes = "03 更新文件数据【id+需要更新字段】", hidden = false)
    @PostMapping("/update")
    public R<List<UploadFile>> update(@ApiParam(name = "params", required = true, allowEmptyValue = false)
                                      @Validated @RequestBody(required = false) UploadFileUpdate uploadFiles) {

配置完成，编译项目，重启项目，访问:项目IP/端口/swagger-ui.html

效果如下：

完成。