Swagger可以帮助后端生成接口文档，并且可以进行接口测试。
使用Swagger你只需要按照它的规范去定义接口及相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网
knife4j是为JAVA MVC 框架集成的Swagger生成Api文档的增强

解决方案

  1. 导入knife4j的maven坐标
    1
    2
    3
    4
    5
    <dependency>
        <grouold>com.github.xiaoymin</grouold>
        <artifactld>knife4j-spring-boot-starter</artifactld>
        <version>3.0.2</version>
    </dependency>
  2. 在配置类中加入kinfe4j的相关配置(WebMvcConfiguration)
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    @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. 设置静态资源映射，否则接口文档无法访问
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    /**
         * 设置静态资源映射
         * 若没有设置静态资源映射 - 则无法打开 localhost:8080/doc.html
         * @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/");
        }

通过Swagger就可以生成接口文档，那么我们就不需要Yapi了？

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

Swagger常用注解

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

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