Swagger

3MNH)R4EM6QVM(LBJ3`I{JM.png

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(swagger.io/)。它的主要作用是：

使得前后端分离开发更加方便，有利于团队协作
接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
功能测试

SpringBoot集成Swagger****

①引入依赖,在heima-leadnews-model和heima-leadnews-common模块中引入该依赖

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

②在common工程中添加一个配置类SwaggerConfiguration（以后企业开发也可重复利用~ ）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

   @Bean
   public Docket buildDocket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              .select()
              // 要扫描的API(Controller)基础包
              .apis(RequestHandlerSelectors.basePackage("com.wuzhou"))
              .paths(PathSelectors.any())
              .build();
   }

   private ApiInfo buildApiInfo() {
      Contact contact = new Contact("程序员","","");
      return new ApiInfoBuilder()
              .title("平台管理API文档")
              .description("后台api")
              .contact(contact)
              .version("1.0.0").build();
   }
}

③在heima-leadnews-common模块中的resources目录中新增以下目录和文件

文件：resources/META-INF/Spring.factories（ springboot容器开启后就会自动加载这个配置了 ）

Swagger常用注解：

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

总结：

controller类 => @Api(value = ”” , tags = ”” , description = ”” )

类中方法 => @ApiOperation( ”” )

实体类 => @ApiModelProperty(value = “” ,required = true)

举例Controller：

@RestController
@RequestMapping("/api/v1/login")
@Api(value = "app端用户登录", tags = "ap_user", description = "app端用户登录API")
public class ApUserLoginController {

    @Autowired
    private ApUserService apUserService;

    @PostMapping("/login_auth")
    @ApiOperation("用户登录")
    public ResponseResult login(@RequestBody LoginDto dto){
        return apUserService.login(dto);
    }
}

举例实体类：

@Data
public class LoginDto {

    /**
     * 手机号
     */
    @ApiModelProperty(value="手机号",required = true)
    private String phone;

    /**
     * 密码
     */
    @ApiModelProperty(value="密码",required = true)
    private String password;
}

启动user微服务，访问地址：http://localhost:51801/swagger-ui.html(端口为微服务的端口)

knife4j

(1)简介

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

gitee地址：gitee.com/xiaoym/knif…

官方文档：doc.xiaominfo.com/

效果演示：knife4j.xiaominfo.com/doc.html

(2)快速集成

pom.xml文件中引入knife4j的依赖,如下

<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

创建Swagger配置文件

在common模块中新建配置类(以后企业开发也可重复利用~)

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Configuration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("1.0")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.wuzhou"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API文档")
                .version("1.0")
                .build();
    }
}

以上有两个注解需要特别说明，如下表

注解	说明
`@EnableSwagger2`	该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
`@EnableKnife4j`	该注解是`knife4j`提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加

添加配置:在Spring.factories中新增配置

访问:在浏览器输入地址：http://host:port/doc.html(端口为微服务的端口)

接口工具swagger、knife4j

Swagger

Swagger常用注解：

knife4j