narrow-vegetable-37489
07/27/2022, 4:20 PMopenapi_definition
for the main OpenAPI file, and openapi_source
for every json/yaml that is part of the definition (aka. referenced by $ref
). The reason a specific openapi_definition
target was added is because OpenAPI tooling usually takes this file as its argument, making it a lot easier to add support for various tools without having to "guess" which openapi_source
files that are "entry points".
It gets quite verbose though, since you'd likely want a file
or resource
for each openapi_source
in order to use the OpenAPI definition in your code. So why not just piggyback off of file
and resource
directly, right? You have your assets and then you can "mark" your main OpenAPI file with openapi_definition
. Well, the problematic part is dependency inference.
Let's say we have this this tree:
.
โโโ BUILD
โโโ a.json
โโโ b.json
โโโ c.json
With this BUILD file:
resources(sources=["*.json"])
openapi_source(source="a.json")
With the JSON files referencing each other (through $ref
) like this:
a.json -> b.json -> c.json
Then we'd want to end up with this dependency graph:
openapi_source(source="a.json") -> resource(source="a.json") -> resource(source="b.json") -> resource(source="c.json")
With the current openapi_definition
and openapi_source
implementation its easy since the OpenAPI backend owns those two target types and can do whatever it wants, but if we start using resource
and file
instead we're suddenly dealing with core targets that may or may not be OpenAPI-related files, and then it gets a bit more complicated.
One option is to let the openapi_source
depend on all three files directly, aka. the graph becomes openapi_source(source="a.json") -> resource(source="a.json") and resource(source="b.json") and resource(source="c.json")
, but that makes ./pants dependencies
, ./pants dependees
, --changed-dependees=transitive
etc. rather unreliable which is suboptimal to say the least.
Another option is for the OpenAPI backend to (optionally?) provide partial dependency inference for AssetSourceField
by simply trying to do its $ref
resolving on any JSON and YAML asset (maybe with some sort of skip field available). This should get us the result we want and I'm leaning towards this solution, but it could potentially be a tad too intrusive.
A third option is to not do any automatic inference and simply leave it up to the user to specific dependencies
between files. (sad face)
The final option is to stick to the intitial implementation, as verbose as it is.
I'd appreciate any and all thoughts and ideas on how to best proceed with this ๐$ref
, e.g. "$ref": "b.json#schemas/foobar"
.$ref
resolving in JSON/YAML `files`/`resources` should be decoupled from the OpenAPI backend altogether? People having JSON schemas in their repository would benefit from it too, and we could offer "partial dependency inference" for other files
and resources
types down the line, like .html could have automatic inference to CSS/JS/images, .css to images etc.fmt
goal that any JSON/YAML user would benefit from, not only those with the OpenAPI backend enabled. So maybe some sort of "general purpose" JSON/YAML backend target towards files
and resources
that includes $ref
resolving?happy-kitchen-89482
07/27/2022, 8:53 PMopenapi_source
targets separate from `files`/`resources`, since these aren't treated like `files`/`resources` - i.e., they are not embedded inside binaries or placed in sandboxes at test time or whatever. They have domain-specific meaning.openapi_sources
(plural) generator, that generates individual openapi_source
(singular) targets per filepython_sources
generating python_source
openapi_definition
is somewhat akin to pex_binary
, in that it points to an "entry point" of sortssources
field (because that same file is already in the sources
of the openapi_source
target and it's generally better to have a file be "owned" by a single target)source
field, which has a specific usage and meaningpex_binary
has no sources
field, and so I'm suggesting that openapi_definition
shouldn't eitheropenapi_sources
generatornarrow-vegetable-37489
07/27/2022, 9:20 PM