如何在@Path路径级别使用@Extension注解生成OpenAPI规范

完全可以在路径级别（类级别@Path对应的路径节点）添加专属的自定义扩展，具体实现如下：

正确代码示例 #

直接在标注了@Path的类上添加@Extension注解即可，与@Tag、@Path同级：

import io.swagger.v3.oas.annotations.Tag;
import io.swagger.v3.oas.annotations.extensions.Extension;
import io.swagger.v3.oas.annotations.extensions.ExtensionProperty;
import jakarta.ws.rs.Path;

@Tag(name = "My beautiful API")
@Path("/api")
@Extension(
    name = "x-custom-options",
    properties = {
        @ExtensionProperty(name = "key", value = "value")
    }
)
public class MyPathClass extends MyBaseClass {}

生成的OpenAPI规范效果 #

这样配置后，生成的OpenAPI规范中，/api路径节点会包含你定义的自定义扩展：

paths:
  /api:
    x-custom-options:
      key: value
    # 该路径下的HTTP操作（GET/POST等）会列在下方

关键注意事项 #

• 必须使用OpenAPI 3.x对应的注解包：io.swagger.v3.oas.annotations.extensions.Extension和ExtensionProperty，不要使用旧版Swagger 2.x的注解（如io.swagger.annotations下的类）。
• 确保依赖版本兼容：Swagger Core 2.x及以上版本（对应OpenAPI 3.x）、OpenAPI Generator 5.x及以上版本，都支持读取类级别的@Extension注解。
• 若父类MyBaseClass也有路径或扩展注解，子类的注解会优先生效或补充父类配置。

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