Springboot入门之集成Swagger

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

1.添加依赖

        <!-- swagger2 -->
        <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>

2.编写SwaggerConfig

@Profile({"test"}) 指定swagger运行环境

@Configuration
@EnableSwagger2
@Profile({"test"})
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("api文档")
                .description("api文档")
                .version("1.0")
                .contact(new Contact("oceanliu", "", "969140406@qq.com"))
                .build();
    }

}

3.编写Controller

/**
 * 用户【api】
 *
 * @author ocean.liu
 */
@Api(tags = "用户")
@RestController
@RequestMapping("/api/user")
public class AllUserApi {

    @Resource
    private IAllUserService allUserService;

    /**
     * @Api 类/接口				 描述类/接口主要用途
     * @ApiOperation 方法         描述方法的用途
     * @ApiImplicitParam 方法     用于描述接口的非对象参数
     * @ApiImplicitParams 方法    用于描述接口的非对象参数集
     * @ApiIgnore 类/方法/参数	 Swagger文档不会显示拥有该注解的接口
     * @ApiModel 参数实体类        可设置接口相关实体的描述
     * ApiModelProperty	         参数实体类属性			可设置实体属性的相关描述
     *
     * @param id
     * @return
     */
    @ApiOperation(value = "用户详情信息")
    @ApiImplicitParam(name = "用户ID", required = true)
    @GetMapping("/{id}")
    public ResultVO<AllUserVO> detail( @PathVariable("id") Integer id) {
        AllUserVO allUserVO = allUserService.get(id);
        return ResultVO.success(allUserVO);
    }

}

4.编写VO

/**
 * 用户信息【vo】
 *
 * @author ocean.liu
 */
@Data
public class AllUserVO {

    @ApiModelProperty(value = "用户ID", example = "1")
    private String userId;

    @ApiModelProperty(value = "用户名称", example = "张先生")
    private String userName;

    @ApiModelProperty(value = "用户真实名称", example = "张三")
    private String userRealName;

}

5.常用注解

@Api :加在Controller类上面，说明这个Controller的作用
@ApiOperation：加在Controller类里面的每个方法上，说明这个方法的作用
@ApiImplicitParams：加在Controller类的方法上，用来说明一组请求参数的含义
@ApiImplicitParam：也是加在Controller类的方法上，用来说明单个请求参数的含义
@ApiModel：加在用于接收请求参数的JavaBean上面，说明这个JavaBean的含义
@ApiModelProperty：加在JavaBean的每个属性上面，说明每个属性的含义

5.禁忌

在生产环境禁用Swagger，避免暴露接口的这种危险行为。