上一篇我们介绍了如何使用Spring Boot快速构建RESTful API “Spring Boot与RESTful API ” ，本篇则介绍一个配合Spring Boot快速构建RESTful文档的工具
由于Spring Boot具有快速开发、便捷部署的特点，很多用户会使用Spring Boot构建RESTful API，一个RESTful接口往往对应不止一个终端，有WEB端、安卓端、IOS端等等。正因为这样，一个接口可能要面对多个开发人员或者团队，为了减少沟通来带的时间成本，大家往往会准备一个RESTful API的文档，但是这种文档往往有几个致命的问题：
- 由于接口过多，细节复杂，文档本身构建起来就比较麻烦
- 随着时间的推移，接口往往会修改或者废弃，这就需要对所有调用方同步文档，如果出现遗漏，很容易造成接口调用失败
为了解决以上问题，就要介绍一下Swagger2，它可以很简单的整合到Spring Boot中，它可以组织出强大的RESTful API文档。效果如图：
此次以上篇文章的代码为例对Swagger2进行讲解。
导入Swagger2依赖
在pom.xml中添加对Swagger2的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>创建Swagger2类
Swagger2类需要与Application.java同级
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
//需要配置正确需要扫面的的包名
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wangxin.restapi"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注：https://my.oschina.net/wangxincj/blog/")
.termsOfServiceUrl("https://my.oschina.net/wangxincj/blog/")
.contact("老虎是个蛋蛋")
.version("1.0")
.build();
}
}
如上所示，
- 添加@Configuration注解，表示让Spring在启动时加载该配置
- @EnableSwagger2表示在Spring Boot中启动Swagger2
- createRestApi方法创建Docket的Bean
- apiInfo()用来创建该API的基本信息
- ApiInfoBuilder实力来控制那些接口需要暴露给Swagger来展现
添加文档内容注解
我们通过使用@ApiOperation注解对接口进行描述，通过@ApiImplicitParam和@ApiImplicitParams对参数进行描述
@RestController
@RequestMapping("/book")
public class BookController {
public static Map<String,Book> bookMap = new HashMap<String,Book>();
/**
* 添加一本书
* @param book
* @return
*/
@ApiOperation(value="创建一本书", notes="创建一本书")
@ApiImplicitParam(name = "book", value = "book实体bean", required = true, dataType = "Book")
@RequestMapping(value="",method = RequestMethod.POST)
public String postBook (@ModelAttribute Book book){
bookMap.put(book.getIsbn(),book);
return "SUCCESS";
}
/**
* 查询出所有book集合
* @return
*/
@ApiOperation(value="查询出所有book集合", notes="")
@RequestMapping(value={""},method = RequestMethod.GET)
public List<Book> getBookList (){
List<Book> bookList = new ArrayList<Book>(bookMap.values());
return bookList;
}
/**
* 根据ISBN获取book
* @param isbn
* @return
*/
@ApiOperation(value="图书详细信息", notes="根据url的isbn来获取图书详细信息")
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
@RequestMapping(value="/{isbn}",method = RequestMethod.GET)
public Book getBook(@PathVariable String isbn){
Book book = bookMap.get(isbn);
return book;
}
/**
* 更新book参数
* @param isbn
* @param book
* @return
*/
@ApiOperation(value="更新图书详细信息", notes="根据url的ISBN来指定更新对象，并根据传过来的book信息来更新图书详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String"),
@ApiImplicitParam(name = "book", value = "图书详细实体book", required = true, dataType = "Book")
})
@RequestMapping(value="/{isbn}",method = RequestMethod.PUT)
public String putBook(@PathVariable String isbn, @ModelAttribute Book book){
Book b = bookMap.get(isbn);
b.setAuthor(book.getAuthor());
b.setName(book.getName());
bookMap.put(isbn,b);
return "SUCCESS";
}
/**
* 根据isbn删除book
* @param isbn
* @return
*/
@ApiOperation(value="删除图书", notes="根据url的ISBN来指定删除图书")
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
@RequestMapping(value="/{isbn}",method = RequestMethod.DELETE)
public String deleteBook(@PathVariable String isbn){
bookMap.remove(isbn);
return "SUCCESS";
}
}
完成以上操作，我们启动Spring Boot，访问http://localhost:8080/swagger-ui.html，即可看到Swagger2生成的RESTful API，如下：
API调试
Swagger2不仅可以生成API文档，还可以在线调试接口，如上图，有两种填写参数方式，第一种是在Parameter列表项中有Book对象需要填写的参数，大家可以根据实际情况填写参数值；第二种方式我们可以点击上图中右侧的Model Schema（黄色区域：它指明了Book的数据结构），此时Value中就有了book对象的模板，我们只需要稍适修改。填写完参数点击“Try it out!”即可完成接口请求。
相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。因此，在构建RESTful API的同时，加入swagger来对API文档进行管理，是个不错的选择。