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
@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

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文档

推荐阅读更多精彩内容