springboot（八）集成Swaggger2

￡神魔★判官ぃ 2023-06-24 03:49 8阅读 0赞

### 文章目录 ###

*   *  Swagger2简介
     *  项目目录
     *  引入依赖
     *  application.yml
     *  建Swagger2配置类
     *  Swagger常用注解
     *  构建测试Controller
     *  测试
     *  项目源码

## Swagger2简介 ##

> Swagger是一款可以快速生成符合RESTful风格API并进行在线调试的插件

## 项目目录 ##

![在这里插入图片描述][20191220134254212.png]

## 引入依赖 ##

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.7.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.7.0</version>
            </dependency>

> 注意如果版本使用最新的2.9.2会有 NoSuchMethodError错误，造成该错误的原因是，Springfox-swagger引用的guava版本相对于你项目中版本较高,此时和低版本的guava引起冲突.  
> 引入高版本依赖就好

<dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>20.0</version>
                <scope>compile</scope>
            </dependency>

这里我使用的2.7所以不会有这个问题

## application.yml ##

server:
      port: 8088
      servlet:
        context-path: /swagger

## 建Swagger2配置类 ##

*  Swagger2Config

@Configuration
    @EnableSwagger2
    public class Swagger2Config { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //为有@Api注解的Controller生成API文档
            // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    //为有@ApiOperation注解的方法生成API文档
            // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //为当前包下controller生成API文档
                    .apis(RequestHandlerSelectors.basePackage("com.midea.swagger.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("springcloud-shopping-swagger")
                    .description("SwaggerUi演示")
                    .contact(new Contact("whbeats", "https://github.com/weihubeats", "641884200@qq.com"))
                    .version("1.0")
                    .build();
        }
    }

## Swagger常用注解 ##

<table> 
 <thead> 
  <tr> 
   <th align="center">注解</th> 
   <th align="center">作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">@Api</td> 
   <td align="center">修饰整个类，描述Controller的作用</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiOperation</td> 
   <td align="center">描述一个类的一个方法，或者说一个接口</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiParam</td> 
   <td align="center">单个参数描述</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiModel</td> 
   <td align="center">用对象来接收参数</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiProperty</td> 
   <td align="center">用对象接收参数时，描述对象的一个字段；</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiResponse</td> 
   <td align="center">HTTP响应其中1个描述</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiResponses</td> 
   <td align="center">HTTP响应整体描述</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiIgnore</td> 
   <td align="center">使用该注解忽略这个API</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiError</td> 
   <td align="center">发生错误返回的信息</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiImplicitParam</td> 
   <td align="center">一个请求参数</td> 
  </tr> 
  <tr> 
   <td align="center">@ApiImplicitParams</td> 
   <td align="center">多个请求参数</td> 
  </tr> 
 </tbody> 
</table>

## 构建测试Controller ##

*  UserController

@RestController
    @RequestMapping("/user")
    @Api(tags = "1.0.0-SNAPSHOT", description = "用户管理", value = "用户管理")
    public class UserController { 
        static User user;
        static List<User> users;
    
        //模拟数据库查询
        static { 
            user = new User();
            users = new ArrayList<>();
            user.setId(10);
            user.setName("奏");
            user.setPassword("123456");
            User user1 = new User();
            user1.setId(20);
            user1.setName("阿离");
            user1.setPassword("6666");
            users.add(user);
            users.add(user1);
        }
    
        @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
        @GetMapping("/{id}")
        public @ResponseBody
        User getUserById(@PathVariable(value = "id") Integer id) { 
            return user;
        }
    
        @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
        @GetMapping("/list")
        public  @ResponseBody List<User> getUserList() { 
            return users;
        }
    
        @ApiOperation(value = "新增用户", notes = "根据用户实体创建用户")
        @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
        @PostMapping("/add")
        public @ResponseBody Map<String, Object> addUser(@RequestBody User user) { 
            Map<String, Object> map = new HashMap<>();
            map.put("result", "success");
            return map;
        }
    
        @ApiOperation(value = "删除用户", notes = "根据用户id删除用户")
        @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
        @DeleteMapping("/{id}")
        public @ResponseBody Map<String, Object> deleteUser(@PathVariable(value = "id") Long id) { 
            Map<String, Object> map = new HashMap<>();
            map.put("result", "success");
            return map;
        }
    
        @ApiOperation(value = "更新用户", notes = "根据用户id更新用户")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path"),
                @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User") })
        @PutMapping("/{id}")
        public @ResponseBody Map<String, Object> updateUser(@PathVariable(value = "id") Long id, @RequestBody User user) { 
            Map<String, Object> map = new HashMap<>();
            map.put("result", "success");
            return map;
        }
    
    
    }

## 测试 ##

访问： http://localhost:8088/swagger/swagger-ui.html  
![在这里插入图片描述][20191220135803862.png]

测试 获取用户  
![在这里插入图片描述][20191220135959129.png]  
![在这里插入图片描述][20191220140017325.png]

## 项目源码 ##

[源码][Link 1]

[20191220134254212.png]: https://img-blog.csdnimg.cn/20191220134254212.png
[20191220135803862.png]: https://img-blog.csdnimg.cn/20191220135803862.png
[20191220135959129.png]: https://img-blog.csdnimg.cn/20191220135959129.png
[20191220140017325.png]: https://img-blog.csdnimg.cn/20191220140017325.png
[Link 1]: https://github.com/weihubeats/springcloud-shopping-parent/tree/master/springcloud-shopping-swagger