# 一.简单介绍

# 1.什么是 swagger

Swagger 是一个开放源代码软件框架,由大型工具生态系统支持,可帮助开发人员设计,构建,记录和使用 RESTful Web 服务。尽管大多数用户通过 Swagger UI 工具识别 Swagger,但是 Swagger 工具集包括对自动文档,代码生成和测试用例生成的支持。

# 2.swagger 特征

  1. 通过代码和注释自动生成文档。在 Swagger 框架下,开发人员可对服务进行归类说明,对方法,模型,返回结果等进行详细说明。方便开发人员在编写代码的同时,编写文档信息。自动生成,只需很少的编辑工作,就能获得完整的 REST APIs 文档

  2. 提供了 UI 界面。既展示接口信息,又提供了参数校验,测试功能

  3. 形成了文档规范,支持不同的语言

  4. 提供丰富的组件。

# 3.pom 依赖包

<properties>
    <swagger-bootstrap-ui.version>1.9.6</swagger-bootstrap-ui.version>
    <swagger.version>2.9.2</swagger.version>
    <swagger-models.version>1.5.24</swagger-models.version>
</properties>
1
2
3
4
5
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>${swagger-models.version}</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>${swagger-models.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
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
29
30

# 二.使用

# 1.swagger 注解

swagger 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述 Controller 的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP 响应其中 1 个描述
  • @ApiResponses:HTTP 响应整体描述
  • @ApiIgnore:使用该注解忽略这个 API
  • @ApiError :发生错误返回的信息
  • @ApiParamImplicitL:一个请求参数
  • @ApiParamsImplicit 多个请求参数
  • @EnableSwaggerBootstrapUI UI 增强
  • @ApiOperationSort 接口排序
  • @ApiSort(value = 5) 给接口排序

# 2.@API

@Api 注解用于标注一个 Controller(Class)。在默认情况下,Swagger-Core 只会扫描解析具有@Api 注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets 等等)的注解。

属性 描述
value url 的路径值
tags 如果设置这个值、value 的值会被覆盖
description 对 api 资源的描述
basePath 基本路径可以不配置
position 如果配置多个 Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为 true 将在文档中隐藏

@Controller
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController extends BaseController {

}
1
2
3
4
5
6
7
8

# 3.@ApiOperation

@ApiOperation 注解在用于对一个操作或 HTTP 方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的 HTTP 请求方法及路径组合构成一个唯一操作。

属性 描述
value url 的路径值
tags 如果设置这个值、value 的值会被覆盖
description 对 api 资源的描述
basePath 基本路径可以不配置
position 如果配置多个 Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为 true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http 的状态码 默认 200
extensions 扩展属性

# 4.@ApiParam

@ApiParam 作用于请求方法上,定义 api 参数的注解。

属性 描述
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为 false
hidden 隐藏该属性
example 举例子
public ResponseEntity<User> getUserById(
@ApiParam(value = "ID of user that needs to be fetched", allowableValues = "range[1,10]", required = true)
@PathVariable("UserId") Long userId)
1
2
3

# 5.@ApiResponses

@ApiResponses、@ApiResponse 进行方法返回对象的说明。

属性 描述
code 数字,例如 400
message 信息,例如"请求参数没填好"
response 抛出异常的类
@ApiResponses({
  @ApiResponse(code = 200, message = "请求成功"),
  @ApiResponse(code = 400, message = "请求参数没填好"),
  @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/user")
public ApiResult getUser(@RequestParam String userId) {
  ...
}
1
2
3
4
5
6
7
8
9
10

# 6.@ApiModel

@ApiModel、@ApiModelProperty @ApiModel 用于描述一个 Model 的信息(这种一般用在 post 创建的时候,使用@RequestBody 这样的场景,请求参数无法使用@ApiImplicitParam 注解进行描述的时候)。

@ApiModelProperty 用来描述一个 Model 的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

/**
 * <pre>
 *     人员信息类
 * </pre>
 *
 */
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{

    @ApiModelProperty(value = "主键", required = true)
    @TableId(value = "id", type = IdType.ID_WORKER)
    private Long id;

    @ApiModelProperty(value = "手机号", required = true)
    private String phonenum;

    @ApiModelProperty(value = "密码", required = true)
    private String password;

    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 7.使用示例

#老版本
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>
1
2
3
4
5
6
#新版本
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>
1
2
3
4
5
6
@ApiOperation("信息软删除")
@Api(tags = "任务")
@ApiModelProperty(value = "离线任务数")
@ApiModel(value = "任务统计")  /
1
2
3
4

# 8.注解汇总

作用范围 API 使用位置
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于 controller 类上
协议描述 @ApiOperation 用在 controller 的方法上
描述返回对象的意义 @ApiModel 用在返回对象类上
Response 集 @ApiResponses 用在 controller 的方法上
Response @ApiResponse 用在 @ApiResponses 里边
非对象参数集 @ApiImplicitParams 用在 controller 的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams 的方法里边

# 三.默认链接

# 1.第一种

#第一种是默认的情况,一般都是这个地址
http://localhost:80/campus-link/swagger-ui.html

# 或者这个
http://localhost/swagger-ui.html

http://localhost:8128/swagger-ui.html
1
2
3
4
5
6
7

# 2.第二种

#第二种
http://localhost:80/swagger/index.html
1
2

# 3.第三种

#第三种
https://beinsight-uat.belle.net.cn/deepexi-dsc-belle-insight/test/command/doc.html

https://localhost:80/doc.html
1
2
3
4

# 4.WebMvcConfigurer

在 WebMvcConfigurer 中开始 swagger 的通行

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/static/**")
            .addResourceLocations("classpath:/static/");
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/swagger-ui.html");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}
1
2
3
4
5
6
7
8
9

# 四.常见问题

# 1.请求实例为 null

@ApiModel(value=“测试”)

这个加在类上的注解 value 不能含有特殊符号. 之前为 com.xxxx.xxxx 然后修改掉 . 即可正常显示入参出参

# 2.版本冲突

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

解决方案:

将 SpringBoot 版本降低到 2.6 以下。

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.6</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
1
2
3
4
5
6

# 五.配置文件

# 1.配置文件


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket openapiApiDoc() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("open-api")
                .pathMapping("/")
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx"))
                //正则匹配请求路径,并分配到当前项目组
                .paths(PathSelectors.ant("/open-api/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("AI补货预测")
                .description("AI补货预测接口文档")
                .version("v1.0")
                .build();
    }
}
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

# 2.pom 文件

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.24</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.24</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
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
29
30

# 3.关闭 swagger

#关闭swagger
swagger.enabled: false
1
2
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled:false}")
    private boolean enabled;

    @Bean
    public Docket openapiApiDoc() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("open-api")
                .pathMapping("/")
                .groupName("11-dsc-11-insight")
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.11"))
                //正则匹配请求路径,并分配到当前项目组
                .paths(PathSelectors.ant("/open-api/**"))
                .build()
                .enable(enabled)
                .globalOperationParameters(globalOperationParameters());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("111")
                .description("111")
                .contact(new Contact("admin", "https://www.11.com", "admin@11.com"))
                .version("v1.0")
                .build();
    }

    private List<Parameter> globalOperationParameters() {

        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("rv-token")
                .description("令牌")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(true)
                .build());

        return parameters;

    }

}
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
上次更新: 10/29/2024, 10:27:50 AM