Change / allow customization of `specs/` directory?

[Jakub Kozłowski]

It appears that specs/ is a hardcoded prefix for OpenAPI files in the http4s-swagger module. My org currently stores these files in a path that's more concrete (has openapi in the name, at least). I'm asking for guidance / opinions on having more flexibility in that area.

The choices, as far as I can see, are:

• move our specs to ./specs. This has pretty obvious compatibility concerns, as any tooling (not managed by my team) will need to be updated to point to that path. It's also a pretty vague word, although that's a nitpick-ish concern.
• change the default (obviously, breaking anyone who's not my org)
• change the implementation to allow passing the prefix as a parameter (low-cost and hopefully/likely binary compatible). This would be my preference.

What would you recommend / be willing to accept?

[Olivier Mélois]

change the implementation to allow passing the prefix as a parameter (low-cost and hopefully/likely binary compatible). This would be my preference.

This. We're already allowing to configure a few things via this construct, just need to add another method.

[Jakub Kozłowski]

I apologize, the problem we were seeing was not related to the specs/ prefix: it was a bit of a mix-up. The prefix is only used for the URI used to serve the given JSON file, it's not actually part of the directory structure in the jar resources. In the jar, the openapi files just land on the top level.

That said, we're facing another problem: the JSON files are part of the codegen's source jar (where the smithy files lie), and for them to be discoverable at runtime we'd have to... well, put these files on the classpath. I see a couple options:

• (easiest) We can simply re-add the same dependencies as what we have in % Smithy4s, but this time without a qualifier (so that they'll be part of the runtime classpath - this is probably not a problem but it does smell a bit).
• Some opt-in in smithy4s's codegen to copy such files from % Smithy4s to target/resources if found? That's probably feature bloat for smithy4s and something too niche for the library.
• Custom resource generator that copies the files from codegen scope, or some other mappings shenanigans in the build tool. This one I dislike the most, as we currently don't have a bespoke sbt plugin, but it's probably the best way, objectively.

[Jakub Kozłowski]

We're going with the former: removing the % Smithy4s qualifier keeps the codegen running and puts everything onto the runtime classpath, so for the short-term this is good enough for most apps. There'll likely be a build tool plugin sometime soon that'll do this in a more principled way.