springboot 整合 Swagger2 学习

一：

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

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

二：

写一个配置类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文档,www.baidu.com")
                .version("1.0")
                .build();
    }
}

三：

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<User> findAll(){
        System.out.println("123456");
        return userService.findAll();
    }


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

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<User> findAll(){
        return userDao.findAll();
    }

    public List<User> findListByParam(User user){
        Example<User> example = Example.of(user);
        return userDao.findAll(example);
    }
}

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,Long> {

    User findByUserName(String userName);

}

四：

运行项目，在浏览器中输入http://localhost:8080/swagger-ui.html

五：

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