Swagger

Swagger相关内容

介绍

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

官网：https://swagger.io/

而我们在IDEA中使用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相关配置

/**
     * 通过knife4j生成接口文档
     *
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档...");
        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"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

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

    /**
     * 设置静态资源映射
     *
     * @param registry
     */
    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/");
    }

然后在浏览器输入url：localhost:8080/doc.html 其中端口号为自己设置的

然后得到如下界面

其可以自动解析你的controller层中的请求并提供相应的接口信息

我们可以在这里进行相关的接口测试

常用注解

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

• @Api

@Api(tags = "员工相关接口")
public class EmployeeController {
    ...
}

• @ApiModel

@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {
    ...
}

• @ApiModelProperty

public class EmployeeLoginVO implements Serializable {

    @ApiModelProperty("主键值")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("jwt令牌")
    private String token;

}

• @ApiOperation

@ApiOperation("员工登录")
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) {
      ...
    }

达到如下效果