利用swagger生成api接口文档

1. swagger出现的背景？
现在的网站架构，前后端分离已经成为一种趋势，前后端的技术在各自的道路上越走远越，后端的框架有常见的spring全家桶，前段也有angular和react等框架。后端主要负责提供服务接口，前段主要负责渲染图形界面，而且前段的展示形式也在多样化，有web端，手机端等。联系前端和后端的主要纽带就是约定好的api文档。但在实际开发中往往api文档不能及时更新，带来一些问题。swagger就是解决这个问题的。

2. swagger简介：
swagger是一个可以用来生成、描述、调用rest风格的web服务。我们可以通过swagger-ui生成后台代码的api接口信息，并且当你改动后台接口的时候，可以同步更新你的接口文档。也可以通过在线的swagger-edit编辑器，利用yaml或者json配置文件生成接口文档，并把生成的文档转化成后台的java代码。我们只需要在生成的代码中写具体的业务逻辑。具体更多的用法参考swagger官网

3. springboot整合swagger，生成后台接口文档

1. 引入maven依赖

   io.springfox
   springfox-swagger2
   2.9.2



   io.springfox
   springfox-swagger-ui
   2.9.2

2. 创建一个swagger注册类

@Component
@EnableSwagger2  // 开启swagger自动配置
public class SwaggerConfigure {

    // controller路径
    private final String basePackage = "com.honeybee.controller";

    /**
     * 配置接口扫描
     *     1.RequestHandlerSelectors.basePackage(basePackage)  扫描具体路径
     *     2.RequestHandlerSelectors.any() 扫描所有接口
     *     3.RequestHandlerSelectors.none() 不扫描接口
     *     4.RequestHandlerSelectors.withMethodAnnotation()  通过方法上的注解扫描
     *     5.RequestHandlerSelectors.withClassAnnotation() 通过类上的注解扫描
     * @return Docket
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                // 配置path过滤规则
                // PathSelectors.any()
                // PathSelectors.none()
                // PathSelectors.regex()
                //.paths(PathSelectors.ant("/*"))
                .build();
    }

    private ApiInfo apiInfo() {
        // 接口联系人信息
        Contact contact = new Contact("HXY", "", "[email protected]");
        // 接口信息
        return new ApiInfo("honeybee", "honeybee", "v1.0",
                "http://localhost:8888", contact, "Honeybee 1.0",
                "", new ArrayList<>());
    }
}

3. 启动项目，访问http://localhost:8888/swagger-ui.html#/，就可以看到生成的接口文档，如图所示
   
   
   
   
   
4. 实体类代码

@Data
@ApiModel(value = "客户信息")
public class CustomerBean implements Serializable {

    @ApiModelProperty(value = "商家Id", required = true)
    private String userId;

    @ApiModelProperty(value = "顾客Id", required = true)
    private String customerId;

    @ApiModelProperty(value = "顾客姓名", required = true)
    private String customerName;

    @ApiModelProperty(value = "顾客电话", required = true)
    private String customerPhone;

    @ApiModelProperty(value = "顾客充值总金额", required = true)
    private double totalMoney;

    @ApiModelProperty(value = "创建时间")
    private Date createTime;

    @ApiModelProperty(value = "更新时间")
    private Date updateTime;

}