Swagger2的配置及使用

亦凉 2022-12-12 15:25 138阅读 0赞

## Swagger2的配置及使用 ##

官网文档：[https://swagger.io/docs/][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”;  
\}

### 使用 ###

**添加依赖**

<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][http_localhost_8080_swagger-ui.html]**（端口号随你项目启动的端口号为准）

完成

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTEwNTUx_size_16_color_FFFFFF_t_70_pic_center]

[https_swagger.io_docs]: https://swagger.io/docs/
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTEwNTUx_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/24cfd3490f09481d8e0105e6ae621920.png