Spring Boot使用Swagger2构建RESTful文档

最新推荐文章于 2024-07-27 13:06:23 发布

00u0o

最新推荐文章于 2024-07-27 13:06:23 发布

阅读量983

点赞数

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!"按钮就可以进行接口测试了，大家也可以自行测试一下其他接口。