Spring Boot中Swagger/OpenAPI如何管理导入模块接口并调整示例字段顺序

一、认证模块接口分组管理 #

你引入的外部认证模块接口，可以通过OpenAPI的分组配置单独归类，和业务自身接口分开，方便查找维护。
如果使用springdoc-openapi依赖，直接新增分组配置类即可：

@Configuration
public class SwaggerGroupConfig {
    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.builder()
                .group("认证相关接口")
                .packagesToScan("com.my.package.ldap.security")
                .build();
    }

    // 业务接口可按需新增其他分组
    @Bean
    public GroupedOpenApi businessApi() {
        return GroupedOpenApi.builder()
                .group("业务接口")
                .packagesToScan("com.my.package.business")
                .build();
    }
}

配置完成后Swagger顶部会出现分组下拉选项，可以单独查看认证模块的所有接口，不会和业务接口混排。

二、请求示例字段排序+可选字段自动隐藏 #

@JsonPropertyOrder不生效的核心原因是默认配置下OpenAPI不会主动读取Jackson的排序注解，结合你需要省去手动删除可选字段的需求，可按以下方案处理：

方案1：快速适配Jackson排序规则（无需修改原有注解） #

直接在项目配置文件中开启对应适配项，即可让已写的@JsonPropertyOrder生效：

• application.properties配置：

# 开启Jackson注解排序适配
springdoc.api-docs.resolve-schema-properties-in-order=true
springdoc.swagger-ui.use-fqn-with-arrays=true

• application.yml配置：

springdoc:
  api-docs:
    resolve-schema-properties-in-order: true
  swagger-ui:
    use-fqn-with-arrays: true

重启服务后字段就会按照你指定的domain -> username -> password顺序展示。

方案2：用OpenAPI原生注解同时解决排序+可选字段问题 #

如果方案1适配后效果不符合预期，可以直接用Swagger原生@Schema注解做配置，优先级最高，同时可以直接指定字段必填性，让非必填字段不出现在默认示例里，省去每次手动删除的步骤：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "认证请求参数")
@JsonPropertyOrder({
    "domain",
    "username",
    "password"
})
public class AuthRequest {
    @Schema(
        description = "认证域",
        requiredMode = Schema.RequiredMode.REQUIRED,
        example = "CORP",
        order = 1
    )
    private String domain;

    @Schema(
        description = "登录用户名",
        requiredMode = Schema.RequiredMode.REQUIRED,
        example = "admin",
        order = 2
    )
    private String username;

    @Schema(
        description = "登录密码",
        requiredMode = Schema.RequiredMode.REQUIRED,
        example = "******",
        order = 3
    )
    private String password;

    // 可选字段标记为非必填，默认示例不会自动带出
    @Schema(
        description = "验证码",
        requiredMode = Schema.RequiredMode.NOT_REQUIRED,
        order = 4
    )
    private String captcha;

    @Schema(
        description = "记住登录状态",
        requiredMode = Schema.RequiredMode.NOT_REQUIRED,
        order = 5
    )
    private Boolean rememberMe;
}

注意：order属性值越小，字段在文档和示例中的排序越靠前。标记为NOT_REQUIRED的字段不会出现在默认生成的请求示例中，调试时不需要手动删除。

老版本Springfox兼容说明 #

如果使用的是已经停更的Springfox（Swagger2），本身不支持直接读取@JsonPropertyOrder配置，除了添加自定义模型排序规则外，更建议直接升级到维护中的springdoc-openapi，Springfox已停止维护3年以上，兼容性问题较多。

内容的提问来源于stack exchange，提问作者saran3h