springboot + Swagger2 学习

一：
在pom.xml中引入Swagger的依赖，代码如下：


         
io.springfox
springfox-swagger2
2.6.1


io.springfox
springfox-swagger-ui
2.6.1

1
2
3
4
5
6
7
8
9
10
二：
写一个配置类Swagger2Config，在类上加上@Configuration注解，表明这是一个配置类，加上@EnableSwagger2注解开启Swagger2的功能。在配置类Swagger2Config中需要注入一个Docket的Bean，该Bean包含了一个apiInfo，即基本API文档的描述信息，以及包扫描的基本包名等信息。代码如下：


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class Swagger2Config {


    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //选择哪些路径和api接口 生成文档
                .select()
                //api接口包扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.springcloud.learn.web"))
                //对所有路径进行监控
                .paths(PathSelectors.any())
                .build();
    }




    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("springboot + swagger api文档")
                .description("springboot + swagger api文档,")
                .version("1.0")
                .build();
    }
}


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38




三：
3.1 简单建一张User表








3.2 web层，代码如下：


import com.springcloud.learn.entity.User;
import com.springcloud.learn.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;


import java.util.List;


@RestController
@RequestMapping("/user")
@Api(value = "用户Controller", description = "用户Controller")
public class UserController {
    @Autowired
    private UserService userService;


    @GetMapping("/findByUserName/{userName}")
    public User findByUserName(@PathVariable("userName") String userName){
        User user = userService.findByUserName(userName);
        return user;
    }


    @ApiOperation(value = "用户列表",notes = "用户列表")
    @PostMapping("/findAll")
    public List findAll(){
        System.out.println("123456");
        return userService.findAll();
    }




    @ApiOperation(value = "用户列表--条件查询" ,notes = "用户列表--条件查询")
    @PostMapping(value = "/findListByParam")
    public List findListByParam(@RequestBody User user) throws Exception {
        List list = userService.findListByParam(user);
        return list;
    }
    
    
    @ApiIgnore//使用该注解忽略这个API
    @PostMapping(value = "/jsonTest")
    public String jsonTest(){
        return "java 天下第一";
    }
}


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
3.3 service层，代码如下：


import com.springcloud.learn.dao.UserDao;
import com.springcloud.learn.entity.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Example;
import org.springframework.stereotype.Service;


import java.util.List;


@Service
public class UserService {
    @Autowired
    private UserDao userDao;


    public User findByUserName(String userName){
        User user = userDao.findByUserName(userName);
        return user;
    }


    public List findAll(){
        return userDao.findAll();
    }


    public List findListByParam(User user){
        Example example = Example.of(user);
        return userDao.findAll(example);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
3.4 dao层，代码如下：


import com.springcloud.learn.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;


import java.util.List;


/**
 * Long 为主键的类型
 */
public interface UserDao extends JpaRepository {


    User findByUserName(String userName);


}
1
2
3
4
5
6
7
8
9
10
11
12
13
四：
运行项目，在浏览器中输入




五：
生成文档的注解//@Api: 修饰整个类，用于描述Controller类
@ApiOperation: 描述类的方法，或者说一个接口
@ApiParam: 单个参数描述
@ApiModel: 用对象来接受参数
@ApiProperty: 用对象来接受参数时，描述对象的一个字段
@ApiResponse: HTTP响应的一个描述
@ApiResponses: HTTP响应的整体描述
@ApiIgnore: 使用该注解，表示Swagger2忽略这个API
@ApiError: 发生错误返回的信息
@ApiParamImplicit: 一个请求参数
@ApiParamsImplicit: 多个请求参数