Correct invalid example in management service OpenAPI spec

[MonkeyCanCode]

The example was incorrectly placed as a sibling of $ref within a schema object in polaris-management-service.yml. According to the OpenAPI specification, properties that are siblings of a $ref are ignored.

This was causing a NullPointerException in OpenAPI Generator v7.13.0+ due to a change in how examples are processed. The generator now expects all examples to be valid and non-empty, and a misplaced example can lead to a null reference when the generator tries to access it (we are not yet using v7.13.0+, thus not a problem at the moment).

This commit moves the example to be a sibling of the schema object, which is the correct placement according to the OpenAPI specification.

Reference error when using newer version of openapi-generator-cli:

openapi-generator-cli generate -i spec/polaris-catalog-service.yaml -g python -o client/python --additional-properties=packageName=polaris.catalog --additional-properties=apiNameSuffix="" --skip-validate-spec --additional-properties=pythonVersion=3.13 --ignore-file-override /local/client/python/.openapi-generator-ignore 
...
  Exception: Cannot invoke "io.swagger.v3.oas.models.examples.Example.getValue()" because the return value of "java.util.Map.get(Object)" is null
	at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1606)
	at org.openapitools.codegen.DefaultGenerator.processPaths(DefaultGenerator.java:1474)
	at org.openapitools.codegen.DefaultGenerator.generateApis(DefaultGenerator.java:663)
	at org.openapitools.codegen.DefaultGenerator.generate(DefaultGenerator.java:1296)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:535)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
Caused by: java.lang.NullPointerException: Cannot invoke "io.swagger.v3.oas.models.examples.Example.getValue()" because the return value of "java.util.Map.get(Object)" is null
	at org.openapitools.codegen.utils.ExamplesUtils.unaliasExamples(ExamplesUtils.java:75)
	at org.openapitools.codegen.DefaultCodegen.unaliasExamples(DefaultCodegen.java:2343)
	at org.openapitools.codegen.DefaultCodegen.fromResponse(DefaultCodegen.java:4934)
	at org.openapitools.codegen.DefaultCodegen.fromOperation(DefaultCodegen.java:4575)
	at org.openapitools.codegen.DefaultGenerator.processOperation(DefaultGenerator.java:1574)
	... 6 more

[singhpk234]

is there a way we can catch this via CI ?

[eric-maynard]

AFAICT CI would catch this if we upgrade to 7.13, but unless we want to start running the generator with multiple versions in CI it might be difficult to catch it without upgrading. Good find though, this should get us closer to being able to upgrade.