Spring Boot使用Swagger2构建RESTful文档

Spring Boot给Java开发人员的生产力带来极大的提高，尤其是构建RESTful API更是方便。使用RESTful服务通常是涉及到多个终端的团队，比如Android、iOS、WEB等。为了让大家沟通顺畅，通常我们需要编写一份详细的RESTful业务接口文档，文档形式有Word或者Excel。但是我们也会发现有如下问题：

• 接口非常多，细节又复杂，如果由程序员高质量的输出一个文档，经常耗时长而且效果也不好，抱怨声不绝与耳。
• 随着时间的推移，文档需要与代码保持同步。但由于大部分程序员都还有着文档不重要的思想，于是总有这样那样的原因导致程序员不愿意或遗忘了更新文档。

我一直认为，代码就是最好的文档，如果能将代码和注释说明很好结合在一块。既减轻了研发人员的负担，又能输出高质量的文档，那就最好不过了。这一点Spring Boot也替我们想到了，那就是RESTful API的重磅好伙伴Swagger2。
具体效果图如下：

RESTful API Docs

下面我们以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@EnableSwagger2public 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

API测试

在上图中我们可以看到book的Value是一个输入框，下方还有一个"Try it out!"按钮。没错，Swagger2还提供了接口测试功能，我们只要按照Book对象的Model Schema(黄色区域)示例进行参数修改，然后点击"Try it out!"按钮就可以进行接口测试了，大家也可以自行测试一下其他接口。

小结

相比编写Word或Excel文档而言，Swagger2虽然对代码有一定的侵入性，但是我个人觉得还是可以接受的，毕竟减少了很多工作量，同时也增加了代码的可读性，非常值得推荐。
对比Swagger2，我还使用过apiDoc这个工具，使用感觉也不错，大家有兴趣也可以去试试看。

完整代码戳这里: Chapter 3-1-3 - 利用Swagger2构建RESTful API文档

文／蓝色的咖啡（简书作者）
原文链接：http://www.jianshu.com/p/897d92ff783c
著作权归作者所有，转载请联系作者获得授权，并标注“简书作者”。