Has anyone used the OpenAPI backend, and would they be able to explain the difference between OpenAPI document and OpenAPI source targets?

maybe @narrow-vegetable-37489 can shed some light

With OpenAPI you always have a "main file" that can optionally reference schemas in other files. All these files (incl. the main one) are the OpenAPI source targets. However, most tooling expects you to give them the path to the main file only and it'll resolve references to all other files automatically. For this purpose the OpenAPI document target was introduced, so it's very easy to distinguish which file is the "entrypoint" of the specification. I guess one could call it the pex_binary of OpenAPI. There some further explanation in the RFC as well :)

Ah okay, thanks I hadn't seen the RFC - I think in lieu of multiple targets, there would have been a world with a single generator and an explicit entrypoint/main - but 🤷 The other question I had was (and hadn't looked into it yet): Is openapi just for the JVM? Or is this caused by a linter/plugin? This felt like a codegen rule, getting hit during lint time

Engine traceback:
  in `lint` goal

MissingRequiredJvmArtifactsInResolve: The JVM resolve `jvm-default` is missing one or more requirements for the OpenAPI Java runtime. Since at least one JVM target type in this repository consumes a `openapi_document` target in this resolve, this resolve must contain `jvm_artifact` targets for each requirement of the OpenAPI Java runtime.

Please add the following `jvm_artifact` target(s) somewhere in the repository and re-run `pants generate-lockfiles --resolve=jvm-default`:

jvm_artifact(
  name="com.google.code.gson_gson",
  group="com.google.code.gson",
  artifact="gson",
  version="2.8.8",
  resolve="jvm-default",
)

jvm_artifact(
  name="org.openapitools_jackson-databind-nullable",
  group="org.openapitools",
  artifact="jackson-databind-nullable",
  version="0.2.2",
  resolve="jvm-default",
)

jvm_artifact(
  name="io.gsonfire_gson-fire",
  group="io.gsonfire",

That seems strange. Maybe @witty-family-13337 can shed some light on it, being the author of the java codegen :)

that's due to having the Java codegen backend enabled. The error is thrown when trying to resolve the dependencies of the

openapi_document

targets that have not opt out from Java code generation. It's not precisely down to actually triggering some codegen during lint time, but I believe that since

spectral

performs a search of transitive targets, this rule will be hit: https://github.com/pantsbuild/pants/blob/ae91cdf241dbfa340b28e09c81b7da16df37ff26/src/python/pants/backend/openapi/codegen/java/rules.py#L248

Man, all that JVM stuff is so greedy in pants 🤦‍♂️ Alright, well, easily enough solved - thanks for the replies!

it is and wish there was a better way of implementing it but I think that in this case it's a combination of dependency inference and that OpenAPI

spectral

linting does a transitive dependency search, which is what triggers the OpenAPI Java Runtime dependency search. I believe that same issue would show with other codegen backends (i.e. Python for Protobuf) but it doesn't show as they don't have linter rules implemented (even though they could have at some point).