接口文档

说明

由于 springfox 与 knife4j 均停止维护 bug众多
选用 springdoc 框架
基于 javadoc 无注解零入侵生成规范的 openapi 结构体
由于框架自带文档UI功能单一扩展性差故移除自带UI 建议使用外置文档工具

系统接口文档规范

OpenAPI 3.0 规范 + SpringDoc
常用核心注解

java

//类
@Tag(name = "用户管理", description = "用户注册、登录、信息管理")

//方法
@Operation(summary = "创建用户", description = "通过用户名和密码注册新用户")

默认文档地址 swagger-ui

升级文档工具

由于框架采用 openapi 行业规范故市面上大部分的框架均支持可自行选择
例如: apifox apipost postman torna knife4j 等根据对应工具的文档接入即可

官网连接: https://www.apifox.cn/

推荐下载客户端软件
注册/登录软件后进行下面操作

方式一（推荐）

TIP

优点：灵活对某一个类进行提交更新接口
缺点：非自动

IDEA 安装插件

获取 Token

测试链接

上传到 ApiFox

效果

方式二

TIP

优点：利用 Apifox 的导入工具，可以自动定时获取数据
缺点：自动刷新周期过长，不能实时刷新

根据项目内所有文档组完成所有数据源创建(拉取后端openapi结构体)
数据源URL格式 http://后端ip:端口/v3/api-docs/组名

text

示例：数据源URL格式
http://localhost:8080/v3/api-docs/1.系统模块

http://localhost:8080/v3/api-docs/9.演示模块


也可不分组统一导入
http://localhost:8080/v3/api-docs

操作如下图：

分享文档

创建分享
预览文档

Springdoc 常用注解

注解	作用	扩展
@Tag(name = "分组名")	API 分组类注解	定义接口模块分组，作用于类或方法。Springdoc 的 @Tag 更灵活，支持 description 字段。
@Operation(summary = "摘要")	接口方法描述	描述单个接口的作用。Springdoc 的 @Operation 支持更多字段，如 tags、hidden 等。
@Parameter(description = "参数说明")	参数描述	描述方法参数。Springdoc 的 @Parameter 支持 required、example 等更细粒度配置。
@Schema(description = "字段说明")	模型字段描述	描述 DTO 或模型的字段。@Schema 支持 example、nullable 等扩展属性。
@ApiResponse(responseCode = "200", description = "成功")	响应结构定义	定义接口返回的 HTTP 状态码和描述。Springdoc 使用 responseCode 替代 code。
@SecurityScheme + @SecurityRequirement	全局安全配置	Springdoc 通过 @SecurityScheme 定义安全方案（如 OAuth2、JWT），并在接口上使用 @SecurityRequirement 绑定。

详细注解使用示例

API 分组与接口描述

java


/**
 * 系统登录
 *
 * @module 系统管理模块
 * @author xijue
 * @Doc <a href='https://www.mmsadmin.com'>MMS文档</a>
 */
@Tag(name = "系统登录",description = "系统登录,鉴权")
@Slf4j
@Validated
@RequiredArgsConstructor
@RestController
@RequestMapping("system/auth")
public class AuthController extends BaseController {

  private final SysLoginService loginService;
  private final SysUserService sysUserService;
  private final SysSignService sysSignService;


  /**
   * 登录方法
   *
   * @param loginBodyBo 登录参数
   * @return 登录结果
   */
  @Operation(summary = "登录方法", description = "登录方法,账号、密码、验证码验证登录")
  @SaIgnore
  @PostMapping("/login")
  public R<Map<String, Object>> login(@Validated @RequestBody LoginBodyBo loginBodyBo, HttpServletRequest request, HttpServletResponse response) {
    Map<String, Object> ajax = new HashMap<>(16);
    // 生成令牌....
    return success(ajax);
  }


  /**
   * 退出登录
   *
   * @return 退出结果
   */
  @Operation(summary = "退出登录", description = "退出当前登录会话")
  @SaIgnore
  @PostMapping("/logout")
  public R<String> logout() {
    loginService.logout();
    return success("退出成功");
  }


}

模型字段描述

java

/**
 * 登录bo
 * @author mmsAdmin
 * @Doc <a href='https://www.mmsadmin.com'>MMS文档</a>
 */
@Data
public class LoginBodyBo {

//  description：参数描述（“账号”）。
//
//  type：string类型
//
//  example：示例值（“demo”），但注意：密码用明文示例存在安全风险！
//
//  maxLength：最大长度（20 字符）。
//
//  minLength：最小长度（6 字符）。
//
//  requiredMode：是否必填（REQUIRED 表示必填，NOT_REQUIRED 表示非必填）。


  /**
   * 用户名
   */
  @Schema(description = "账号",type = "string", example = "demo", maxLength = 16, minLength = 3, requiredMode = Schema.RequiredMode.REQUIRED)
  @NotBlank(message = "账号不能为空")
  @Size(min = 3, max = 16, message = "账号长度在{min}到{max}个字符")
  private String username;

  /**
   * 用户密码
   */
  @Schema(description = "账号密码", type = "string",example = "******", maxLength = 32, minLength = 6, requiredMode = Schema.RequiredMode.REQUIRED)
  @NotBlank(message = "密码不能为空")
  @Size(min = 6, max = 32, message = "密码长度在{min}到{max}个字符")
  private String password;
  /**
   * 验证码
   */
  @Schema(description = "验证码",type = "string", example = "1234J0",requiredMode = Schema.RequiredMode.NOT_REQUIRED)
  private String code;
  /**
   * 验证码Key
   */
  @Schema(description = "验证码Key",type = "string", example = "1234J0",requiredMode = Schema.RequiredMode.NOT_REQUIRED)
  private String codeKey;
  /**
   * uuid
   */
  @Schema(description = "uuid",type = "string", example = "e5cd7e4891bf95d1d19206ce24a7b32e",requiredMode = Schema.RequiredMode.NOT_REQUIRED)
  private String uuid;
  /**
   * 记住我
   */
  @Schema(description = "记住我",type = "boolean", example = "true",requiredMode = Schema.RequiredMode.NOT_REQUIRED)
  private Boolean rememberMe=true;

}

安全认证配置

java

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme(
        name = "Authorization",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT"
)
public class OpenApiConfig {

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
            // 添加全局安全要求（所有接口默认需要认证）
            .addSecurityItem(new SecurityRequirement().addList("Authorization"));
  }
}

java

@Operation(security = {})  // 覆盖为无需认证
@PostMapping("/login")
public ResponseEntity<AuthResponse> login(...) { ... }

接口文档 ​

说明 ​

系统接口文档规范 ​

升级文档工具 ​

方式一（推荐） ​

方式二 ​

分享文档 ​

Springdoc 常用注解 ​

详细注解使用示例 ​

接口文档

说明

系统接口文档规范

升级文档工具

方式一（推荐）

方式二

分享文档

Springdoc 常用注解

详细注解使用示例