Swagger介绍及应用

介绍：

        使用Swagger只需要按照它的规范去定义接口以及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。

        官网：https://swagger.io/

        注意：Yapi是设计阶段所使用的工具，管理和维护接口，而Swagger实在开发阶段使用的框架，帮助后端开发人员做后端的接口测试。

        Knife4j 是为Java MVC框架集成Swagger生成的Api文档的增强解决方案。

        使用方式：

                1.导入knife4j的maven坐标

                添加依赖：

                <dependency>

                                <groupId>com.github.xiaoymin</groupId>

                                <artifactId>knife4j-spring-boot-starter</artifactId>

                                <version>3.0.2</version>

                </dependency>

                2.在配置类中加入knife4j的相关配置

                

@Bean
public Docket docket(){
    ApiInfo apiInfo = new ApiInfoBuilder()
          .title("接口文档")
          .version("2.0")
          .description("描述")
          .build();

    Docket docket = new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo)
          .select()
          //指定生成接口需要扫描的包
          .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user"))
          .paths(PathSelectors.any())
          .build();
    return docket;
}

                3.配置静态资源映射，否则接口文档页面无法访问。

protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

配置完成之后，启动程序

在浏览器页面中输入localhost:8080/doc.html#/home即可打开接口文档。

Swagger的常用注解

        通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

        @Api(tags="")： 用在类上，如Controller ，表示对类的说明。

        @ApiModel         用在类上，如entity，DTO，VO

        @ApiModelProperty         用在属性上，描述属性信息。

        @ApiOperation(value="")        用在方法上，如Controller的方法，说明方法的用途和作用。