Spring Boot给Java开发人员的生产力带来极大的提高，尤其是构建RESTful API更是方便。使用RESTful服务通常是涉及到多个终端的团队，比如Android、iOS、WEB等。为了让大家沟通顺畅，通常我们需要编写一份详细的RESTful业务接口文档，文档形式有Word或者Excel。但是我们也会发现有如下问题：
- 接口非常多，细节又复杂，如果由程序员高质量的输出一个文档，经常耗时长而且效果也不好，抱怨声不绝与耳。
- 随着时间的推移，文档需要与代码保持同步。但由于大部分程序员都还有着文档不重要的思想，于是总有这样那样的原因导致程序员不愿意或遗忘了更新文档。
我一直认为，代码就是最好的文档，如果能将代码和注释说明很好结合在一块。既减轻了研发人员的负担，又能输出高质量的文档，那就最好不过了。这一点Spring Boot也替我们想到了，那就是RESTful API的重磅好伙伴 Swagger2。
具体效果图如下：
下面我们以Chapter 3-1-1: 构建一个复杂的RESTful API及单元测试中的代码为例，看看如何将Swagger2集成到Spring Boot工程中创建一个RESTful API文档
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配置类
在RestApplication.java同级路径下创建SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("使用Swagger2构建RESTful APIs")
.description("客户端与服务端接口文档")
.termsOfServiceUrl("http://localost:8080")
.contact("bluecoffee")
.version("1.0.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.bluecoffee.rest"))
.paths(PathSelectors.any())
.build();
}
}
上述代码中，通过@Configuration注解，让Spring来加载该类配置，通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后，apiInfo是用来创建接口文档的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
创建API接口描述信息
@RestController
@RequestMapping(value="/books")
public class BookController {
// 创建线程安全的Map
static Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());
@ApiOperation(value="获取书籍列表", notes="")
@RequestMapping(value={"/"}, method=RequestMethod.GET)
public List<Book> getBookList() {
// 处理"/books/"的GET请求，用来获取图书列表
// 还可以通过@RequestParam传递参数来进行查询条件或者翻页信息的传递
List<Book> r = new ArrayList<Book>(books.values());
return r;
}
@ApiOperation(value="创建书籍", notes="根据Book对象创建书籍")
@ApiImplicitParam(name = "book", value = "书籍实体对象Book", required = true, dataType = "Book")
@RequestMapping(value="/", method=RequestMethod.POST,produces = "application/json")
public JsonResult createBook(@RequestBody Book book) {
// 处理"/books/"的POST请求，用来创建User
// 除了@ModelAttribute绑定参数之外，还可以通过@RequestParam从页面中传递参数
books.put(book.getBookId(), book);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
@ApiOperation(value="获取书籍详细信息", notes="根据URL中的bookId来获取书籍详细信息")
@ApiImplicitParam(name = "bookId", value = "书籍ID", required = true, dataType = "Long")
@RequestMapping(value="/{bookId}", method=RequestMethod.GET)
public Book getBook(@PathVariable Long bookId) {
// 处理"/books/{id}"的GET请求，用来获取url中id值的Book信息
// url中的id可通过@PathVariable绑定到函数的参数中
return books.get(bookId);
}
@ApiOperation(value="更新书籍信息", notes="根据URL中的bookId来指定更新书籍，并根据传过来的Book信息来更新书籍详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "bookId", value = "书籍ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "book", value = "书籍详细实体book", required = true, dataType = "Book")
})
@RequestMapping(value="/{bookId}", method=RequestMethod.PUT)
public JsonResult putBook(@PathVariable Long bookId, @RequestBody Book book) {
// 处理"/books/{bookId}"的PUT请求，用来更新Book信息
Book b = books.get(bookId);
b.setTitle(book.getTitle());
b.setAuthor(book.getAuthor());
books.put(bookId, b);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
@ApiOperation(value="删除书籍", notes="根据URL中的bookId来指定删除书籍")
@ApiImplicitParam(name = "bookId", value = "书籍ID", required = true, dataType = "Long")
@RequestMapping(value="/{bookId}", method=RequestMethod.DELETE)
public JsonResult deleteBook(@PathVariable Long bookId) {
// 处理"/books/{bookId}"的DELETE请求，用来删除Book
books.remove(bookId);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
}
我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
完成这些工作后，我们再启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html。就能看到之前所展示的RESTful API的页面。我们可以再点开具体的API请求，以POST类型的/books/为例：
API测试
在上图中我们可以看到book的Value是一个输入框，下方还有一个"Try it out!"按钮。没错，Swagger2还提供了接口测试功能，我们只要按照Book对象的Model Schema(黄色区域)示例进行参数修改，然后点击"Try it out!"按钮就可以进行接口测试了，大家也可以自行测试一下其他接口。
小结
相比编写Word或Excel文档而言，Swagger2虽然对代码有一定的侵入性，但是我个人觉得还是可以接受的，毕竟减少了很多工作量，同时也增加了代码的可读性，非常值得推荐。
对比Swagger2，我还使用过apiDoc这个工具，使用感觉也不错，大家有兴趣也可以去试试看。
