Swagger的使用 - 技术栈

介绍

使用Swagger 你只需要按照它的规范去定义接口及接口相关的信息,就可以做到生成接口文档 ,以及在线接口调试页面 。

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

使用Swagger

SpringBoot2整合knife4j

1.导入Knife4j的maven坐标

XML 复制代码

<dependency>
<groupld>com.github.xiaoymin</groupld>
<artifactld>knife4j-spring-boot-starter</artifactld>
<version>3.0.2</version>
</dependency>

2.编写配置类WebMvcConfiguration，继承WebMvcConfigurationSupport类在配置类中加入knife4j的相关配置

java 复制代码

@Bean
public Docket docket(){
Apilnfo apilnfo = new ApilnfoBuilder()
.title("苍穹外卖项目接口文档")
.version("2.0")
.description("苍穹外卖项目接口文档")
.build();

Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apilnfo(apilnfo)
.select()
//指定生成接口需要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
.paths(PathSelectors.any())
.build();

return docket;

}

3.在配置类中重写父类的方法设置静态资源映射，否则接口文档页面无法访问

java 复制代码

/ **
*设置静态资源映射
* @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/");

常用注解

SpringBoot3整合Knife4j

1.导入依赖

XML 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>

2.在配置文件中配置相关属性

bash 复制代码

# springdoc-openapi项目访问访问地址: http://127.0.0.1:8080/doc.html
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    # path: 配置swagger-ui.html/UI界面的访问路径,默认为/swagger-ui.html
    tags-sorter: alpha
    # tags-sorter: 接口文档中的tags排序规则,默认为alpha,可选值为alpha(按字母顺序排序)或as-is(按照在代码中定义的顺序排序)
    operations-sorter: alpha

  api-docs:
    path: /v3/api-docs
    # path: 配置api-docs的访问路径,默认为/v3/api-docs

  group-configs:
    # group-configs: 配置分组信息
    - group: 'default'
      # group: 分组名称
      paths-to-match: '/**'
      # paths-to-match: 配置要匹配的路径,默认为/**
      packages-to-scan: cn.bytewisehub.pai.web
      # packages-to-scan: 配置要扫描的包的路径,直接配置为Controller类所在的包名即可

# knife4j项目访问访问地址:http://127.0.0.1:8080/doc.html#/home
knife4j:
  enable: true
  # 设置为true以启用Knife4j增强功能,这将再应用程序中启用Knife4j UI
  setting:
    # language: 设置Knife4j UI的语言,默认为zh_cn,可选值为zh_cn或en
    language: zh_cn
  #开启生产环境屏蔽
  production: false
  #是否启用登录认证
  basic:
    enable: true
    username: # 自己设置一个
    password: # 自己设置一个

3.添加配置类配置

java 复制代码

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
        // 接口文档标题
        .info(new Info().title("标题")
              // 接口文档简介
              .description("描述")
              // 接口文档版本
              .version("版本");
    }
}

常用注解

（1）类级别注解

@Operation

用于描述控制器类中的单个操作。
java 复制代码
@Operation(summary = "获取用户列表", description = "返回所有用户的列表")
@GetMapping("/users")
public List<User> getUsers() {
    // ...
}
属性：

summary：简短描述。

description：详细说明。

tags：标签，用于分类API。

responses：响应描述

@Tag

用于为API操作分组。
java 复制代码
@Tag(name = "用户管理", description = "用户相关操作")
@RestController
@RequestMapping("/users")
public class UserController {
    // ...
}
属性：

name：标签名。

description：标签描述。

（2）方法级别注解

@Operation

用于描述单个操作，类似于类级别使用方式。
java 复制代码
@Operation(summary = "获取用户列表", description = "返回所有用户的列表")
@GetMapping("/users")
public List<User> getUsers() {
    // ...
}
属性：

summary：简短描述。

description：详细说明。

tags：标签，用于分类API。

responses：响应描述。

@ApiResPonses

用于描述API操作的响应。

属性：

value：包含多个@ApiResponse注解。

@ApiResponse

用于描述单个响应。
java 复制代码
@Operation(summary = "获取用户列表")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "400", description = "请求参数错误"),
    @ApiResponse(responseCode = "404", description = "找不到资源"),
    @ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@GetMapping("/users")
public List<User> getUsers() {
    // ...
}
属性：

responseCode：HTTP状态码。

description：描述信息。

content：响应内容类型和模式。

（3）参数级别注解

@Parameter

用于描述单个参数

java 复制代码

@Operation(summary = "获取用户详情")
@GetMapping("/{id}")
public User getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) {
    // ...
}

属性：

name：参数名。
description：参数描述。
required：是否必须参数。
schema：参数模式。

@Parameters

用于描述多个参数

java 复制代码

@Operation(summary = "分页获取用户列表")
@Parameters({
    @Parameter(name = "page", description = "页码", required = true, schema = @Schema(type = "integer", example = "1")),
    @Parameter(name = "size", description = "每页数量", required = true, schema = @Schema(type = "integer", example = "10"))
})
@GetMapping("/users")
public List<User> getUsersByPage(@RequestParam int page, @RequestParam int size) {
    // ...
}

value：包含多个@Parameter注解。

（4）模型类注解

@Schema

用于描述模型类和字段的信息。
java 复制代码
@Schema(description = "用户实体")
public class User {
    
    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "Alice")
    private String name;

    @Schema(description = "用户年龄", example = "30")
    private Integer age;

    // getters and setters
}
description：字段描述。

example：示例值。

required：是否必须字段。

type：字段类型。

@ArraySchema

用于描述数组类型的字段。
java 复制代码
@Schema(description = "用户列表")
public class UserListResponse {

    @ArraySchema(schema = @Schema(implementation = User.class), description = "用户数组")
    private List<User> users;

    // getters and setters
}
schema：数组元素的模式。

description：数组描述。