springfox wagger2 自动生成接口文档[Spring Boot]

1. 添加依赖 pom.xml

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

2. 创建swagger配置文件SwaggerConfig.java

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {
    @Bean
    public Docket swaggerSpringMvcPlugin(){

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("** APIs")
                .description("**的接口文档")
                .version("1.0.0")
                .termsOfServiceUrl(null)
                .contact(new Contact("name", "url", "email"))
                .license("作者:**")
                .licenseUrl("http://")
                .build();

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .select()
                //.paths(regex("/api/*")) // 指定接口url 
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo)
                .useDefaultResponseMessages(false);

        return docket;
    }
}

3. 配置具体的接口注释数据的简单示例，更多的注释可参看官网
   • @Api() 用于controller类
   • @ApiOperation()用于controller的方法

ApiOperation(value = "/api/edit", notes = "", httpMethod = "POST", response = Response.class)

• @ApiResponses用于controller的方法，响应的数据

@ApiResponses({
        @ApiResponse(code = 100 , message = "请选择部门"),
        @ApiResponse(code = 101, message = "请选择日期")
})

• @ApiImplicitParams()用于controller的方法，参数注释

@ApiImplicitParams({
        @ApiImplicitParam(name = "department", value = "部门", required = true, paramType = "form"),
        @ApiImplicitParam(name = "date", value = "日期", required = true, paramType = "form")
})

name 参数
value 参数的描述
required 是否必传
paramType 参数存放位置：header、query、path(resuful接口)、body、form
dataType 参数类型
defaultValue 参数默认值

• @ApiModel() 用于bean对象的类

@ApiModel(value = "", description = "")

• @ApiModelProperty()(用于bean对象的方法

@ApiModelProperty(value = "", name="")

value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

• @ApiParam()具体请求参数

@ApiParam(name = "", value = "", required = true)

name 参数
value 参数简单描述
defaultValue 描述参数默认值
allowableValues 可接收参数值限制
required 是否为必传参数

4. 与spring security配合
   使用了spring security时，需要登录访问，或者在security配置文件中添加对url的忽略。

public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers(         
                "/swagger-ui.html",
                 "/webjars/**",
                "/v2/api-docs",
                "/swagger-resources",
                "/swagger-resources/configuration/ui",
                "/swagger-resources/configuration/security"
                );
    }
}

5.访问 ip:port/swagger-ui.html

image.png

6. 控制swagger关闭和启动
   SwaggerConfig.java中添加注释@ConditionalOnExpression("${swagger.enable:true}")
application.properties更改：true启动，false关闭，线上系统需要关闭。