使用Swagger2构建Spring Boot RESTful AIP 文档

原创
2016/12/23 23:00
阅读数 4.2K

    上一篇我们介绍了如何使用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文档进行管理,是个不错的选择。

 

展开阅读全文
打赏
0
61 收藏
分享
加载中

引用来自“程序猿DD”的评论

引用来自“wuyiw”的评论

http://blog.didispace.com/springbootswagger2/ 是不是同一个作者啊~
我在这里。。。感谢支持。。。😱

回复@程序猿DD :
2017/01/16 14:39
回复
举报

引用来自“wuyiw”的评论

http://blog.didispace.com/springbootswagger2/ 是不是同一个作者啊~
我在这里。。。感谢支持。。。😱
2017/01/16 12:57
回复
举报
http://blog.didispace.com/springbootswagger2/ 是不是同一个作者啊~
2016/12/28 22:31
回复
举报

引用来自“java9”的评论

1. 先写文档,再生成代码的情况下,生成的代码不是你想要的。
2. 对于参数是一个类这样的情况,不能像表单那样的形式提交参数,而是在request body中,是json格式。

@java9 所以我这边提到了两种提交方式
2016/12/26 13:56
回复
举报
1. 先写文档,再生成代码的情况下,生成的代码不是你想要的。
2. 对于参数是一个类这样的情况,不能像表单那样的形式提交参数,而是在request body中,是json格式。
2016/12/26 10:28
回复
举报
更多评论
打赏
5 评论
61 收藏
0
分享
返回顶部
顶部