SpringBoot2 整合Swagger 2.9.1

对于咱后台来说,写完代码再写文档是十分难受的(主要是自己写的代码都不想看第二眼)

上干货

一.在pom.xml中引入 swagger 依赖

        
            io.springfox
            springfox-swagger2
            2.9.1
            
                
                    io.swagger
                    swagger-annotations
                
                
                    io.swagger
                    swagger-models
                
            
        
        
            io.springfox
            springfox-swagger-ui
            2.9.1
        
        
        
            io.swagger
            swagger-annotations
            1.5.21
        
        
            io.swagger
            swagger-models
            1.5.21
        

二.编写 Swagger2Config 文件

@Configuration
@EnableSwagger2
public class Swagger2 implements WebMvcConfigurer {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxx文档")
                .description("xx文档")
                .termsOfServiceUrl("http://dev-master.zgzhongnan.com")
                .contact("xxxx")
                .version("1.0")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 配置servlet处理
     */
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }

}

三.编写 controller 类

@Api(tags = "设备管理", description = "萤石设备管理")
@RestController
@RequestMapping("/smart/equipo")
public class EquipoController {

    @Resource
    EquipoAPIService equipoAPIService;

    @ApiOperation(value = "添加设备", notes = "添加设备")
    @ApiImplicitParams(
        {
            @ApiImplicitParam(name = "houseId" ,value = "房屋id",required = true,paramType="query",dataType = "Long"),
            @ApiImplicitParam(name = "userId" ,value = "用户id",required = true,paramType="query",dataType = "Long"),
            @ApiImplicitParam(name = "deviceSerial" ,value = "设备序列号",required = true,paramType="query",dataType = "String"),
            @ApiImplicitParam(name = "validateCode" ,value = "设备验证码",required = true,paramType="query",dataType = "String")
        }
    )
    @ApiResponses({
            @ApiResponse(code=200,message="操作成功")
    })
    @PostMapping("/addEquipo")
    @ResponseBody
    public JSONObject addEquipo(Long houseId,Long userId,String deviceSerial,String validateCode) {
        return equipoAPIService.addEquipo(houseId,userId,deviceSerial,validateCode);
    }
}

四.访问 Swagger 页面

浏览器输入 ip:端口/项目地址/swagger-ui.html

五.注意事项(精华)

1. 大家在引入 swagger 的时间千万不要引入太新的版本,因为你可能会踩未知的雷
2. 建议在引入 swagger 时同时引入 swagger-annotations swagger-models ,不然你可能遇到传参失败的问题
3. 虽然我们配置了重写SpringBoot默认静态资源访问地址,但我们也要注意自己所用的框架中有木有重写SpringBoot静态资源这块的代码,要不然你会一直访问不到 swagger-ui.html 页面
4. 在 controller 类中 尽量使用 @ApiImplicitParam 注解定义方法入参,不要用 @ApiParam 注解,@ApiImplicitParam 注解中的paramType 类型没特殊要求就写 query ,不要问为什么,自己试试就知道了