. Swagger2 rest风格接口文档快速开发工具

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

​ 当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：

1. 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2. 跨语言性，支持 40 多种语言。
3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

基本使用

1.引入依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>

2.在启动类开器功能

@SpringBootApplication
@MapperScan("com.sangeng.mapper")
@EnableSwagger2//Swagger2接口文档维护工具
@EnableScheduling//项目启动开始执行同步功能
public class HcySpringBootApplition {

    public static void main(String[] args) {


        SpringApplication.run(HcySpringBootApplition.class,args);

    }
}

3访问文机ip;
访问：http://localhost:7777/swagger-ui.html 注意其中localhost和7777要调整成实际项目的域名和端口号。

测试结果

注解优化

1. @Api 俩个属性 一个是为接口写标签和描述
   
   此时的运行接口
   2. @ApiOperation 因为每个cotroller有多个接口 所以使用该注解经行标识
   代码如下:

运行结果:

3. @ApiImplicitParam 用于描述接口的参数，但是一个接口可能有多个参数，所以一般与 @ApiImplicitParams 组合使用。

运行结果:

4. 实体类配置
@ApiModel

@ApiModel用于描述实体类。

这里用来写在dto上,在Mabtieplus中,修改记录和传入记录都是传入实体类,可是这样并不利于代码维护和规范 ,应该区别开来,所以重写一个结构和domain一样的伪实体类(不需要Mp映射)接受添加方法传入的参数,然后经行存储时候在用,工具类·经行转换即可
beancopyutils

/**
 * 工具类一般定义类方法
 * 定义bean拷贝
 */
public class BeanCopyUtils {
    private BeanCopyUtils() {
    }
    //todo 之前的beancopy 复杂在于还需要自身创建对象经行复制 用反射在方法体类 逆向生成对象
    public  static <V> V copyBean(Object source, Class<V> clazz){//泛型 定义后返回的方法对象只能是这个类型 (这样就省去了强转换的步骤)
        //todo 创建目标对象
        V result=null;
        try {
             result = clazz.newInstance();//反射 通过字节码文件生成对象
            //todo 实现属性拷贝
            BeanUtils.copyProperties(source,result);
            //todo 返回结果


        } catch (InstantiationException e) {
            e.printStackTrace();
        } catch (IllegalAccessException e) {
            e.printStackTrace();
        }
      return result;
  }
  public  static <O,V> List<V> copyBeanList(List<O> list,Class<V> clazz) {
        return    list.stream()//字节流 相当于 for
                .map(o -> copyBean(o,clazz))//调用上面的方法
                .collect(Collectors.toList());//收集起来做成集合

  }
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "添加评论dto")
public class AddCommentDto{
    //..
}

5. 实体的属性的描述配置@ApiModelProperty

@ApiModelProperty用于描述实体的属性

    @ApiModelProperty(notes = "评论类型（0代表文章评论，1代表友链评论）")
    private String type;

6. 文档信息配置

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sangeng.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("团队名", "http://www.my.com", "my@my.com");
        return new ApiInfoBuilder()
                .title("文档标题")
                .description("文档描述")
                .contact(contact)   // 联系方式
                .version("1.1.0")  // 版本
                .build();
    }
}

结果: