Swagger + Knife4j 接口文档整合

什么是接口文档？

写接口信息的文档。

每个接口的信息包括：

• 请求参数

• 响应参数

• 错误码

• 接口地址

• 接口名称

• 请求类型

• 请求格式

• 备注

谁用接口文档？

答：一般是后端或者负责人来提供，后端和前端都要使用。

为什么需要接口文档？

• 有个书面内容（背书或者归档），便于大家参考和查阅，便于 沉淀和维护 ,方便使用

• 接口文档便于前端和后端开发对接，前后端联调的介质 。后端 => 接口文档 <= 前端

• 好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率

  怎么做接口文档？

  手写：比如腾讯文档、Markdown 笔记

  自动化接口文档生成：自动根据项目代码生成完整的文档或在线调试的网页。Swagger、 Postman（侧重接口管理）（国外）；apifox、apipost、eolink（国产）

使用 Swagger

1. 引入依赖（Swagger 或 Knife4j： https://doc.xiaominfo.com/knife4j/documentation/get_start.html）pom.xml中

<!--        swager 引入-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

 <!-- https://doc.xiaominfo.com/knife4j/documentation/get_start.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

1. 自定义 Swagger 配置类 -swaggerConfig

package com.yunjin.api_backed.config;

import org.springframework.beans.factory.config.BeanPostProcessor;
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;

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径,控制器类包
                .apis(RequestHandlerSelectors.basePackage("com.yunjin.api_backed"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("**平台接口文档")
                //创建人
                .contact(new Contact("***", "https://gitee.com/peng-yunjing",
                        "3049352171@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("系统API描述")
                .build();
    }

    //版本報錯,在启动类中配置 # 支持 swagger3
    //  mvc:
    //    pathmatch:
    //      matching-strategy: ant_path_matcher

}

1. 定义需要生成接口文档的代码位置（Controller） 更改路径

2. 千万注意：线上环境不要把接口暴露出去!(可以通过在 SwaggerConfig 配置文件开头 加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启)

3. 启动即可

4. 可以通过在 controller 方法上添加 @Api、@ApiImplicitParam(name = "name",value = "姓名",required = true) @ApiOperation(value = "向客人问好") 等注解来自定义生 成的接口描述信息

具体版本使用看meavn文档

如果 springboot version >= 2.6，需要application.yml中添加如下配置：

  # 支持 swagger3
  mvc:
      pathmatch:
        matching-strategy: ant_path_matcher

访问

localhost:端口号/docs.html

恭喜你，又学会一点