Spring boot — 利用Swagger2构建RESTful API文档

Swagger2的优势

在前后端分离，写接口文档较繁琐。利用 Swagger2我们可以做到：

1. 无需编写任何文档
2. 页面直观
3. 可调式

上大图：

有这么多的好处，还不赶紧下手？话说，我就先下手为强了~~~

Swagger2的使用

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2. 配置Swagger2

在Application.java同级下创建Swagger2.

@Configuration       //让spring加载此类配置
@EnableSwagger2      //启动swagger2
public class Swagger2 {

    @Bean
    public Docket  createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sugar.springbootlearning"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("sugar xxx project RESTful APIs")
                .description("see more")
                .termsOfServiceUrl("https://github.com/yangshuting1")
                .contact("sugar")
                .version("1.0")
                .build();
    }
}

3. 填充文档信息

由于为了有更好的交互体验，我们要拿出我们法宝：

1. @ApiOperation: 修饰API
2. @ApiImplicitParams: 方法的参数进行说明

@RestController               //@RestController: 可以返回json 相比较于@Controller
@RequestMapping("/product")  // @RequestMapping :配置URL映射
public class ProductController {

    /**
     * date: 2018-05-11
     * author： yangshuting
     * */
    @ApiOperation("创建产品")
    @RequestMapping(value = "", method = RequestMethod.POST)
    public boolean createProduct(@RequestBody CreateProductOption CreateProductOption){
        return true;
    }

    @ApiOperation("获取产品")
    @RequestMapping(value = "/{productId}", method = RequestMethod.GET)
    public Product getProduct(@PathVariable long productId){
        Product product = new Product();
        product.setId(productId);
        product.setName("笔记本");
        product.setDeleted(0);
        return product;
    }
}

之后运行spring boot,在浏览器页面输入：http://localhost:8080/swagger-ui.html就可以出来效果了。

4 调试和查看

API 详情图如下：

可以进行查看和输入参数进行try,是不是很方便呐！！！

代码示例：sugar2-3

参考文章如下：http://blog.didispace.com