Selectively Generate Specific Routes in Client

[kwhitehouse]

Background
We're currently using Guardrail to generate a client for a large API surface. We'd love to selectively generate only the handful of routes that we use, rather than the (almost) 100 that are defined by the server. The server is not owned by our team, so we don't have control over their API surface. We want to avoid editing the openapi yaml specification, since it's very convenient to copy-paste this directly from the Swagger specification.

Other Relevant Tickets
This is somewhat related to two other tickets I found that request the opposite feature - namely, the ability to filter out certain routes.

• Skip route in server generation #183
• Allow for ignoring certain schemas with vendor extension #941

Proposed Feature
As noted above, we'd like to avoid editing the openapi yaml. It would be ideal to include this as a parameter within the ScalaClient stanza.

    Compile / guardrailTasks := List(
        ScalaClient(
          file("some.openapi.yaml"),
          pkg = "some.package",
          generatePathsAllowList = List("/api/v1/hello", "/api/v1/world")
        )
      )

Some iterations on this idea:

• For the two issue tickets linked above, we could expose a similar parameter generatePathsBlockList which would generate methods for all specified paths except those listed.
• Instead of focusing on paths, it might make sense to focus on operationId, since it's possible some users might want to generate code only for get but not for post methods. Alternatively, we could continue using paths, but also introduce an generateHttpMethodsAllowlist. If so, then users could specify both generatePathsAllowList = List("/api/v1/hello", "/api/v1/world") and generateHttpMethodsAllowlist = List("get") to create a generated "read-only" client that only included get methods on the two specified paths.

[blast-hardcheese]

Hello, thanks for the detailed issue!

I wonder if this is an opportunity for a preprocessing step in the yaml directly, instead of functionality missing from guardrail.

I wonder if it's possible to curate a set of $ref's from the file you pass in to guardrail into the larger specification. You'd also need to do the same thing for the components, but it might give the kind of fine grained control you need using what's already part of the spec today.

What do you think?

[stanislav-chetvertkov]

Handling it with preprocessing sounds like a right way to approach it, ideally, one should be able to see the spec after it's been processed just to make sure everything is correct vs letting guardrail do it in-memory + it adds extra complexity because it might obscure error messages (the spec would not be the original one).

Doing the preprocessing in SBT shouldn't be difficult though for Maven I think it's not as straightforward which makes it worth adding it to guardrail.

[blast-hardcheese]

@kwhitehouse Did you have any thoughts on either my or Stanislav's thinking here? If there's something we can do to get started here, or if you've tried the OpenAPI $ref approach and it's working for you, it'd be great to hear 🙂