学习springBoot（14）集成 swagger2但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发

1、简介

前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，

但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

2、添加依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
<!--增强版ui-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

3、添加swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${sw2.swTitle}")
    private String swTitle;

    @Value("${sw2.swTermsOfServiceUrl}")
    private String swTermsOfServiceUrl;

    @Value("${sw2.swVersion}")
    private String swVersion;

    @Value("${sw2.swDescription}")
    private String swDescription;

    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
//                .apis(RequestHandlerSelectors.any()) //扫描所有
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //扫描包含“ApiOperation”注解的方法
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title(swTitle)
                //条款地址
                .termsOfServiceUrl(swTermsOfServiceUrl)
                .version(swVersion)
                //描述
                .description(swDescription)
                .build();
    }
}

application.yml

信息写在配置文件里，这样灵活一点

sw2:
  swTitle: Spring Boot Swagger2 构建RESTful API
  swTermsOfServiceUrl:
  swVersion: 1.0
  swDescription: API 接口描述

4、测试接口

@ApiOperation(value = "根据id查询图书",notes = "采用restfull风格",httpMethod = "GET")
@ApiImplicitParam(name = "id",value = "主键",dataType="int",required = true)
@RequestMapping(value="/list2/{id}")
@ResponseBody
public Book list2(@PathVariable(value = "id") Integer id){
    Book book = bookService.findById(id);
    return book;
}

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

5、访问

启动项目

swagger-ui: http://IP:PORT/swagger-ui.html

增强版ui： http://IP:PORT/doc.html

感觉还是增强版的好用一点，更适合实际使用