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<Book, Integer>, JpaSpecificationExecutor<Book> {
}

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文件上添加依赖

        <!-- swagger生成接口API -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- 接口API生成html文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

在实体类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";
    }
}

（蓝字为添加内容）