SpringBoot集成Swagger2

首先说一下这个东西的作用：它可以很轻松整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。简单说就是Swagger2可以很方便帮我们生成RESTful API文档，提高协同开发效率。

常用注解：

定义在类上：@Api

定义在方法上：@ApiOperation

定义在参数上：@ApiParam

定义在实体类上：@ApiModel

定义在实体类属性上：@ApiModelProperty

例如：

@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@TableName("edu_course_collect")
@ApiModel(value="CourseCollect对象", description="课程收藏")
public class CourseCollect extends BaseEntity {

    private static final long serialVersionUID=1L;

    @ApiModelProperty(value = "课程讲师ID")
    private String courseId;

    @ApiModelProperty(value = "课程专业ID")
    private String memberId;
    
}

@Api(tags = "讲师管理")
@RestController
@RequestMapping("/admin/edu/teacher")
public class TeacherController {

    @Autowired
    private TeacherService teacherService;

    @ApiOperation("所有讲师列表")
    @GetMapping("list")
    public List<Teacher> listAll() {
        return teacherService.list();
    }

    @ApiOperation(value = "根据ID删除讲师",notes = "根据ID删除讲师，逻辑删除")
    @DeleteMapping("remove/{id}")
    public boolean removeById(@ApiParam(value = "讲师ID",required = true) @PathVariable String id){
        return teacherService.removeById(id);
    }

}

创建一个SpringBoot工程，添加相关的依赖

<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>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

然后就是Swagger2配置了，这很简单很轻松，只需要你自己提供一个Docket的Bean。

这里我建了一个config包，将SwaggerConfig类写在里面。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

然后运行SpringBoot项目，访问http://localhost:8080/swagger-ui.html就可以看到一个界面了。到这里集成就基本完毕。

下面进行CRUD的测试。

我们去建一个User类，用来测试使用。我这里放在entity层，

注意：前三个注解是Lombok的注解，后面关于Api开头的注解都是Swagger提供的，主要效果是在项目运行后生成的html中有一些附加信息，可以不加的。

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;
}

接下来我们去写数据操作，新建dao层一个UserDao接口和他的实现类。为了方便，我就不引入数据库了，我使用map来做数据的CRUD。

public interface UserDao {
    Collection<User> findAll();
    User findById(Integer id);
    void delete(Integer id);
    void save(User user);
}

@Repository
public class UserDaoImpl implements UserDao {

    private static Map<Integer,User> userMap;

    static {
        userMap = new HashMap<>();
        userMap.put(1,new User(1,"乐心湖1",181));
        userMap.put(2,new User(2,"乐心湖2",182));
        userMap.put(3,new User(3,"乐心湖3",183));
    }
    @Override
    public Collection<User> findAll() {
        return (userMap.values());
    }

    @Override
    public User findById(Integer id) {
        return userMap.get(id);
    }

    @Override
    public void delete(Integer id) {
        userMap.remove(id);
    }

    @Override
    public void save(User user) {
        userMap.put(user.getId(),user);
    }
}

controller层下建UserController类

@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserDao userDao;

    @GetMapping("/findAll")
    @ApiOperation("查询所有用户")
    public Collection<User> findALl(){
        return userDao.findAll();
    }

    @GetMapping("/findById/{id}")
    @ApiOperation("根据id查询用户")
    public User findById(@PathVariable Integer id){
        return userDao.findById(id);
    }

    @PutMapping("/save")
    @ApiOperation("添加或者修改用户")
    public void save(@RequestBody User user){
        userDao.save(user);
    }

    @DeleteMapping("/delete/{id}")
    @ApiOperation("根据id删除用户")
    public void delete(@PathVariable Integer id){
        userDao.delete(id);
    }

}

重新运行项目，刷新页面。