No OpenAPI schema generated for Class annotated with `@Schema`

[michaelkoepf]

Hi,

Disclaimer: I am not sure if this issue should be opened in this repo or rather there. Trying it here first.

I use io.quarkus:quarkus-smallrye-openapi via the Quarkus Operator SDK extensions BOM (version details below). I have an object annotated with org.eclipse.microprofile.openapi.annotations.media.Schema.

package com.example;

import org.eclipse.microprofile.openapi.annotations.media.Schema;

@Schema(description = "Policy specification.")
public final class TestPolicySpec {

  @Schema(description = "Value.")
  private String value;

  public String getValue() {
    return value;
  }

  public void setValue(final String value) {
    this.value = value;
  }
}

For this object, the OpenAPI spec should be generated. My configuration for smallrye-openapi is as follows.

quarkus.smallrye-openapi.store-schema-directory=./openapi-spec
quarkus.smallrye-openapi.auto-add-server=false

When running the build (./gradlew clean build), the respective OpenAPI files are generated, but do not contain the annotated object.

---
openapi: 3.1.0
paths: {}
info:
  title: Generated API
  version: "1.0"

Version details:

quarkusPluginVersion=3.24.2
quarkusPlatformVersion=3.24.2

The complete example source code can be found here: https://github.com/michaelkoepf/openapi-gen-test

Thank you.

--
Best,
Michael

[michaelkoepf]

Update: When I pull in io.quarkus:quarkus-resteasy as a dependency, the OpenAPI spec for the class annotated with @Schema is generated as expected.

---
openapi: 3.1.0
components:
  schemas:
    TestPolicySpec:
      description: Policy specification.
      type: object
      properties:
        value:
          type: string
          description: Value.
info:
  title: openapi-gen-test API
  version: 1.0.0-SNAPSHOT
paths: {}

I am not sure if this behavior is expected or not.

[metacosm]

Hi @michaelkoepf,
What's the intended outcome of this effort? Just so that we get a better idea of what you're trying to accomplish…

Note that, while CRDs do indeed create a new API endpoint on the Kubernetes server, they're not API endpoints from the perspective of the operator as a Quarkus application, i.e. you cannot start your operator app and query it via your browser like you would a typical REST application that would be documented by OpenAPI. From that perspective, using OpenAPI in this scenario seems a little out of scope but maybe I'm not understanding your use case correctly.

[xstefank]

I think this is expected - https://github.com/quarkusio/quarkus/blob/main/extensions/smallrye-openapi/deployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiProcessor.java#L136.

The main OpenAPI Processor. This will scan for JAX-RS, Spring and Vert.x Annotations, and, if any, add supplied schemas.

As Chris said above, QOSDK doesn't provide any of these out of the box.

This should be probably documented in the official guide too.

[michaelkoepf]

@metacosm The goal is to generate end user documentation for the CRD. In particular, a script will parse the generated OpenAPI spec and generate Markdown tables from it. While I know this is not the primary use case (and also that there are no REST OpenAPI endpoints as per your note -- thank you btw for that) smallrye-openapi is included in the BOM. And the @ Schema annotation is well-known by developers, so it is convenient to reuse them for my scenario.

I am also open to other suggestions how to achieve my goal. I just want to avoid creating the docs manually.

Thank you.

[metacosm]

@michaelkoepf perhaps you could use the schema generated as part of the CRD instead?