Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inconsistent handling of custom extensions in the generated OpenAPI documentation #2883

Closed
MateuszPe opened this issue Feb 1, 2025 · 1 comment
Labels
invalid This doesn't seem right

Comments

@MateuszPe
Copy link

MateuszPe commented Feb 1, 2025

Describe the bug
There is inconsistent handling of custom extensions in the generated OpenAPI documentation when using springdoc-openapi. Specifically, custom extension properties without the x- prefix are not added to the OpenAPI definition in recent versions.
It seems that this breaking change was not described in the release notes, causing unexpected behavior for users upgrading from earlier versions.

To Reproduce
Generate openapi for a controller with a defined custom extension.

@RestController
@RequestMapping("/hello")
class HelloWorldController {

  @Operation(
      summary = "Hello World",
      description = "Returns a simple Hello World message",
      extensions = {
          @Extension(
              properties = {
                  @ExtensionProperty(name = "custom-extension", value = "custom-extension-value")
              }
          )
      }
  )
  @GetMapping
  public String helloWorld() {
    return "Hello World";
  }
}

To generate openapi below test can be used:

@SpringBootTest
@AutoConfigureMockMvc
class OpenapiGenerationTest {

  @Autowired
  private MockMvc mockMvc;

  @Test
  void shouldGenerateOpenapi() throws Exception {
    MvcResult result = mockMvc.perform(get("/v3/api-docs"))
        .andDo(print())
        .andExpect(MockMvcResultMatchers.status().isOk())
        .andExpect(MockMvcResultMatchers.content().contentType("application/json"))
        .andReturn();

    Path filePath = Paths.get("openapi-docs.json");
    Files.write(filePath, result.getResponse().getContentAsString().getBytes());
  }
}
  • What version of spring-boot you are using?
    3.4.2

  • What modules and versions of springdoc-openapi are you using?
    springdoc-openapi-starter-webmvc-api v2.8.4
    springdoc-openapi-starter-common v2.8.4

  • What is the actual and the expected result using OpenAPI Description (yml or json)?
    Library does not add custom exception to openapi definition.
    Generated openapi specification must have defined by annotations extension.

  • Provide with a sample code (HelloController) or Test that reproduces the problem

@RestController
@RequestMapping("/hello")
class HelloWorldController {

  @Operation(
      summary = "Hello World",
      description = "Returns a simple Hello World message",
      extensions = {
          @Extension(
              properties = {
                  @ExtensionProperty(name = "custom-extension", value = "custom-extension-value")
              }
          )
      }
  )
  @GetMapping
  public String helloWorld() {
    return "Hello World";
  }
}

Expected behavior
Generated openapi must have extension in definition.

Additional context
2.6.0 - this version generates extension property "as it is". Name of the extension is exactly the same as defined by user.
2.7.0 - this version generates extension property with x- if extension property name is not prefixed with x-. It it is prefixed then generated definition contains extension property.
2.8.0 - this version generates extension property ONLY when it was defined whit prefix x-. Otherwise extension property is not present in openapi definition.

@bnasslahsen
Copy link
Collaborator

@MateuszPe,

2.8.x is based on OAS 3.1: Refer to https://swagger.io/specification/
This object MAY be extended with Specification Extensions, though as noted, additional properties MAY omit the x- prefix within this object.

You can still use old behavior by switching to OAS 3.0:

springdoc.api-docs.version= openapi_3_0

@bnasslahsen bnasslahsen added the invalid This doesn't seem right label Feb 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
invalid This doesn't seem right
Projects
None yet
Development

No branches or pull requests

2 participants