Swagger2的配置及使用

Swagger2的配置及使用

官网文档：https://swagger.io/docs/

Swagger是什么

1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

swagger的基础注解介绍

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象实体来作为入参
• @ApiProperty：用对象接实体收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams： 多个请求参数

1、@Api修饰整个类，描述Controller的作用

2、@ApiOperation ，用于描述一个方法或者接口

可以添加的参数形式：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

3、@ApiParam单个参数描述

@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

4、@ApiImplicitParam 一个请求参数

@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

@ApiOperation(value = “根据用户名获取用户的信息”,notes = “查询数据库中的记录”,httpMethod = “POST”,response = String.class)
@ApiImplicitParam(name = “userName”,value = “用户名”,required = true,dataType = “String”,paramType = “query”)
5、@ApiImplicitParams 多个请求参数

参数和@ApiImplicitParam一致，只是这个注解可以添加多个参数而已

@ApiImplicitParams({
@ApiImplicitParam(name = “nickName”,value = “用户的昵称”,paramType = “query”,dataType = “String”,required = true),
@ApiImplicitParam(name = “id”,value = “用户的ID”,paramType = “query”,dataType = “Integer”,required = true)
})
public String getUserInfoByNickName(String nickName, Integer id) {
return “1234”;
}

使用

添加依赖

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

编写配置类：SwaggerConfig .java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 多人开发对个分组
     * @return
     */
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fly");
    }

    /**
     * 配置Swagger的Docket的bean实例
     * @param environment
     * @return
     */
    @Bean
    public Docket docket(Environment environment){
        //设置要显示swagger的环境
        Profiles profiles=Profiles.of("dev","test");
        //获取项目环境
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable：false关闭swagger
                .enable(flag)
                .groupName("flyfly")
                .select()
                //RequestHandlerSelectors，配置要扫描的接口方式：basePackage：指定要扫描的包
                //any()：扫描全部；none()：不扫描；withClassAnnotation:扫描类上的注解，参数是一个反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.fly.controller"))
                //paths()：过滤路径
                //.paths(PathSelectors.ant("/fly/**"))
                .build();
    }

    /**
     * 配置swagger的apiInfo信息
     * @return
     */
    private ApiInfo apiInfo() {
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("flyfly", "", "xxx");
        return new ApiInfo("飞飞的Swagger Api文档",
                "xx系统",
                "v1.0",
                "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

添加文档注释

@Api(value = "user控制层")
@RestController
public class UsersController {
    @Autowired
    private UsersService usersService;

    @RequestMapping(value = "/delete", method = RequestMethod.POST)
    @ApiOperation(value = "根据id删除用户", httpMethod = "POST",response = Integer.class)
    @ApiImplicitParam(name = "userId",value = "用户id",required = true,dataType = "Integer",paramType = "delete")
    public Integer delete(Integer userId) {
        System.out.println(userId);
        int result = usersService.delete(userId);
        return result;
    }

    @RequestMapping(value = "/update", method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "修改用户", httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "user",value = "用户实体类",required = true,dataType = "String",paramType = "update")
    public String update(Users user) {
        int result = usersService.update(user);
        if (result >= 1) {
            return "修改成功";
        } else {
            return "修改失败";
        }

    }

    @RequestMapping(value = "/insert", method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "添加用户", httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "user",value = "用户实体类",required = true,dataType = "String",paramType = "add")
    public Users insert(Users user) {
        return usersService.insertUser(user);
    }

    @RequestMapping("/ListUser")
    @ResponseBody
    @ApiOperation(value = "查询全部用户", httpMethod = "POST",response = String.class)
    @ApiImplicitParam(required = true,dataType = "String",paramType = "select")
    public List<Users> ListUser() {
        return usersService.listUser();
    }

    @RequestMapping("/ListByName")
    @ResponseBody
    @ApiOperation(value = "通过用户名模糊查询", httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "String",paramType = "select")
    public List<Users> ListUserByName(String userName) {
        return usersService.findByName(userName);
    }

    /**
     * 分页
     * @return
     */
    @RequestMapping(value="/page")
    @ResponseBody
    @ApiOperation(value = "分页查询", httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "page",value = "页数",required = true,dataType = "String",paramType = "select")
    public List<Users> page(Integer page){
        int pageNow = page == null ? 1 : page;
        int pageSize = 5;
        int startRows = pageSize*(pageNow-1);
        List<Users> list = usersService.queryPage(startRows);
        return list;
    }

    /**
     * rows
     * @return
     */
    @RequestMapping(value="/rows")
    @ResponseBody
    @ApiOperation(value = "获取总条数", httpMethod = "POST",response = Integer.class)
    @ApiImplicitParam(required = true,dataType = "int",paramType = "select")
    public int rows(){
        return usersService.getRowCount();
    }
}

打开浏览器，输入http://localhost:8080/swagger-ui.html（端口号随你项目启动的端口号为准）

完成