swagger在springboot上的简单使用

背景：

    在用springboot开发项目时，api接口写好后不知是否能正常运行，这个时候就需要测试了。

    项目结构图：

    代码：

        Book

@Entity
@Table(name = "t_book")
public class Book {

    @Id
    @GeneratedValue
    private Integer id;

    @Column(length = 100)
    private String name;

    private Float price;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Float getPrice() {
        return price;
    }

    public void setPrice(Float price) {
        this.price = price;
    }
}

        BookDao

public interface BookDao extends JpaRepository, JpaSpecificationExecutor {
}

        BookController

@Controller
@RequestMapping("/book")
public class BookController {

    @Resource
    private BookDao bookDao;

    @PostMapping("/add")
    @ResponseBody
    public String add(Book book) {
        bookDao.save(book);
        return "add success";
    }
}

    如上，若要测试/book/add接口，由于是post方法提交，则需要写一个from表单进行测试，这样无疑加大了后端人员的工作负担。

    因此，在这里正式介绍今天的主角——swagger。

    随着时代发展，现在的网站开发前后端关系已是越来越少，api接口是前后端人员的唯一纽带，可想其重要性。如上所说，如果后端人员在测试api接口是需要写前端代码，这样显然不是一个高效的开发方式。而swagger不仅能在线测试接口，而且对接口文档进行实时更新，也更利于管理。

    那事不宜迟，现在来看看如何在springboot上使用swagger

使用

    在pom文件上添加依赖

        
        
            io.springfox
            springfox-swagger2
            2.7.0
        

        
        
            io.springfox
            springfox-swagger-ui
            2.7.0
        

    在实体类Book添加注解

@Entity
@Table(name = "t_book")
public class Book {

    @Id
    @GeneratedValue
    @ApiModelProperty("图书id")//swagger注解，对实体属性的描述
    private Integer id;

    @Column(length = 100)
    @ApiModelProperty("书名")//swagger注解，对实体属性的描述
    private String name;

    @ApiModelProperty("价格")//swagger注解，对实体属性的描述
    private Float price;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Float getPrice() {
        return price;
    }

    public void setPrice(Float price) {
        this.price = price;
    }
}

    在控制层BookController添加注解

@Controller
@RequestMapping("/book")
@EnableSwagger2//启用Swagger2
public class BookController {

    @Resource
    private BookDao bookDao;

    @ApiOperation("新增图书")//用于方法，表示一个http请求的操作
    @PostMapping("/add")
    @ResponseBody
    public String add(@ApiParam("from表单封装的book实体")//用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等） Book book) {
        bookDao.save(book);
        return "add success";
    }
}

    （蓝字为添加内容）

测试

    运行springboot程序，在浏览器输入http://localhost:8080/swagger-ui.html，出现以下页面

    输入数据

    点击 Try it out! 展示出测试结果 

    查看数据库

    数据库成功显示数据，说明此接口能正确运行

总结

    用了swagger之后，后端人员测试接口就完全碰前端代码了，开发效率得到了提高。而且在有多个controller的时候swagger也会自动帮你整理好多个api接口，只要你写代码的时候写好swagger的注解，在运行swagger的时候就相当于自动生成一份api文档，岂不是美滋滋？