guardrail-dev / guardrail-dev/guardrail
Selectively Generate Specific Routes in Client
- Dominant language
- Scala
- Stars
- 541
- Forks
- 138
- PR merge metrics
- No merged PRs in 30d
Description
**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.
* https://github.com/guardrail-dev/guardrail/issues/183
* https://github.com/guardrail-dev/guardrail/issues/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.
Contributor guide
Research direction
Start with the ScalaClient configuration path and compare the filtering requests in issues 183 and 941. Resolve whether selection should use paths, operationId, HTTP methods, or a combination, then verify that generated clients contain exactly the selected operations without requiring edits to the OpenAPI YAML.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, scala
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100