Swagger详解

1 介绍

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

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

2 使用方式

2.1 导入knife4j的maven坐标

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-spring-boot-starterartifactId>
    <version>3.0.2version>
dependency>

2.2 在配置类中加入knife4j相关配置

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

2.3 设置静态资源映射，否则接口文档无法访问

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

3 Swagger和Yapi?

1. Yapi是设计阶段使用的工具、管理和维护接口
2. Swagger在开发阶段使用的框架，帮助后端开发人员做后端的接口测试。

4 Swagger的常用注解？

@Api 用在类上，例如Controller，表示对类的说明

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

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

@ApiOperation 用在方法上，例如Controller的方法，说明方法的用途、作用