使用Swagger2构建Spring Boot RESTful AIP 文档

    上一篇咱们介绍了如何使用Spring Boot快速构建RESTful API “Spring Boot与RESTful API ” ，本篇则介绍一个配合Spring Boot快速构建RESTful文档的工具

    因为Spring Boot具备快速开发、便捷部署的特色，不少用户会使用Spring Boot构建RESTful API，一个RESTful接口每每对应不止一个终端，有WEB端、安卓端、IOS端等等。正由于这样，一个接口可能要面对多个开发人员或者团队，为了减小沟通来带的时间成本，你们每每会准备一个RESTful API的文档，可是这种文档每每有几个致命的问题：

1. 因为接口过多，细节复杂，文档自己构建起来就比较麻烦
2. 随着时间的推移，接口每每会修改或者废弃，这就须要对全部调用方同步文档，若是出现遗漏，很容易形成接口调用失败

    为了解决以上问题，就要介绍一下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文档进行管理，是个不错的选择。

• swagger官网