引言

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务

一款致力于解决接口规范化、标准化、文档化的开源库

官方网站：https://swagger.io/

Knife4j是集Swagger2及OpenAPI3为一体的增强解决方案

官方网站：https://doc.xiaominfo.com/

基本概念

接口参数：

  • 请求参数

  • 响应参数

    • 错误码

  • 接口地址

  • 接口名称

  • 请求类型

  • 请求格式

  • 备注

作用：

  • 有书面内容，方便大家参考、查阅、维护
  • 便于前后端对接，介质，后端 => 接口文档 <= 前端
  • 在线调试、在线测试，提高开发效率

入门:

1、添加依赖：

1
2
3
4
5
6
7
8
9
10
11
12
<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!--swagger ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、整合SpringBoot

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 标注接口（Controller）位置
                .apis(RequestHandlerSelectors.basePackage("com.wu.pro_match.controller"))
                .paths(PathSelectors.any())
                .build();

    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("pro-match")
            .description("pro-match的API文档")
            .termsOfServiceUrl("https://github.com/Miaowzhz")
            .version("1.0")
            .build();
    }
}

knife4j

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

可以理解为 Swagger 的升级，有更好看的 ui 界面

1、添加依赖

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.8</version>
</dependency>

2、整合SpringBoot

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    @Bean(value = "productApi")
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 标注接口（Controller）位置
                .apis(RequestHandlerSelectors.basePackage("com.wu.pro_match.controller"))
                .paths(PathSelectors.any())
                .build();

    }
    /**
     * api 信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("pro-match")
                .description("pro-match的API文档")
                .termsOfServiceUrl("https://github.com/Miaowzhz")
                .version("1.0")
                .build();
    }
}

注意：

如果 springboot 版本 大于等于 2.6 ，需要在application.yml中添加配置：

1
2
3
4
spring:
	mvc:
    	pathmatch:
      		matching-strategy: ant_path_matcher

效果：

1.png