Skip to content

Commit 0f86b87

Browse files
authored
feat: add OpenAPI-generated API client (#1)
* feat: add OpenAPI client generation pipeline openapi generator (java, native library, pinned 7.23.0) generates the API client from convoy's docs/v3/openapi3.yaml. scripts/generate.sh mirrors only com.getconvoy.{api,client,models}; the hand-written verify package is never touched. sdk_generation.yaml matches the convoy dispatcher contract (filename + force/feature_branch inputs) used by convoy.js and convoy-python, and compiles + tests before opening a PR. * feat: add generated API client output of scripts/generate.sh against convoy main's openapi3.yaml. event data fields are open maps (Map<String, Object>) and a round-trip regression test guards against payload keys being dropped. * test: add route contract test and pin regen workflow to main offline contract test proves verb, path, auth header, and JSON body for createEndpointEvent against a local JDK http server. the regen workflow now checks out main explicitly so a dispatch from another ref cannot commit generated output onto the wrong base. * fix: block ref-qualified feature_branch names refs/heads/main would bypass the literal main check and force-push the default branch. refs/* is now rejected like other protected shapes.
1 parent d7f3579 commit 0f86b87

217 files changed

Lines changed: 66301 additions & 9 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
name: SDK Generation
2+
3+
# Generator: OpenAPI Generator (java, native library) via scripts/generate.sh.
4+
#
5+
# Keeps the same workflow filename and dispatch inputs as the other SDK repos
6+
# (convoy.js, convoy-python) so the frain-dev/convoy dispatcher
7+
# (speakeasy-sdk.yml) works unchanged.
8+
9+
on:
10+
workflow_dispatch:
11+
inputs:
12+
force:
13+
# Accepted for dispatcher compatibility. Generation is deterministic
14+
# from the spec, so there is nothing to force: no diff means no PR.
15+
description: Accepted for compatibility; regeneration is always run
16+
required: false
17+
default: "false"
18+
type: string
19+
feature_branch:
20+
description: Branch for SDK changes
21+
required: false
22+
type: string
23+
schedule:
24+
- cron: "0 6 * * 1"
25+
26+
# Serialize generations: overlapping cron/dispatch runs race on the same
27+
# branch/PR. Queue instead of cancel so a triggered regen is never dropped.
28+
concurrency:
29+
group: sdk-generation
30+
cancel-in-progress: false
31+
32+
permissions:
33+
contents: write
34+
pull-requests: write
35+
36+
jobs:
37+
generate:
38+
runs-on: ubuntu-latest
39+
steps:
40+
- name: Checkout Code
41+
uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
42+
with:
43+
# Regen branches are always derived from main: the spec is pulled
44+
# from convoy main, so a dispatch from another ref must not silently
45+
# commit generated output onto that ref's base.
46+
ref: main
47+
# Prefer a PAT: PRs opened with GITHUB_TOKEN do not trigger
48+
# pull_request workflows, so verify CI would never run on them.
49+
token: ${{ secrets.SDK_BOT_PAT || secrets.GITHUB_TOKEN }}
50+
51+
- name: Setup Java
52+
uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
53+
with:
54+
distribution: temurin
55+
java-version: "17"
56+
57+
- name: Regenerate client
58+
run: ./scripts/generate.sh
59+
60+
- name: Compile and test regenerated client
61+
# Never open a PR for a client that does not compile or breaks the
62+
# verify tests. PR CI (ci.yml) re-proves this on the PR itself.
63+
run: ./gradlew test
64+
65+
- name: Detect changes
66+
id: diff
67+
run: |
68+
if git diff --quiet && [ -z "$(git status --porcelain)" ]; then
69+
echo "changed=false" >> "$GITHUB_OUTPUT"
70+
echo "No client changes; skipping PR." >> "$GITHUB_STEP_SUMMARY"
71+
else
72+
echo "changed=true" >> "$GITHUB_OUTPUT"
73+
fi
74+
75+
- name: Prepare feature branch
76+
if: steps.diff.outputs.changed == 'true'
77+
id: branch
78+
env:
79+
# Never interpolate free-form dispatch inputs into run: directly.
80+
FEATURE_BRANCH_INPUT: ${{ inputs.feature_branch }}
81+
run: |
82+
if [ -n "$FEATURE_BRANCH_INPUT" ]; then
83+
# SDK PRs must come from a reviewable feature branch, never a
84+
# protected ref or an option-looking / metacharacter name.
85+
# refs/* is blocked too: "refs/heads/main" would bypass the
86+
# literal main check and force-push the default branch.
87+
case "$FEATURE_BRANCH_INPUT" in
88+
main|master|release/*|refs/*|-*|*[!a-zA-Z0-9._/-]*)
89+
echo "::error::Invalid feature_branch '$FEATURE_BRANCH_INPUT'"
90+
exit 1
91+
;;
92+
esac
93+
echo "name=$FEATURE_BRANCH_INPUT" >> "$GITHUB_OUTPUT"
94+
else
95+
echo "name=sdk-regen-$(date -u +%Y%m%d)" >> "$GITHUB_OUTPUT"
96+
fi
97+
98+
- name: Push branch and open PR
99+
if: steps.diff.outputs.changed == 'true'
100+
env:
101+
GH_TOKEN: ${{ secrets.SDK_BOT_PAT || secrets.GITHUB_TOKEN }}
102+
BRANCH: ${{ steps.branch.outputs.name }}
103+
run: |
104+
git config user.name "github-actions[bot]"
105+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
106+
107+
git checkout -B "$BRANCH"
108+
git add -A
109+
git commit -m "feat: regenerate API client from OpenAPI spec"
110+
# Force push is safe: the regen branch is fully derived from main
111+
# plus this deterministic generation; any previous content is stale.
112+
git push --force origin "$BRANCH"
113+
114+
existing=$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')
115+
if [ -z "$existing" ]; then
116+
gh pr create \
117+
--head "$BRANCH" \
118+
--title "feat: regenerate API client from OpenAPI spec" \
119+
--body "Automated regeneration via OpenAPI Generator (java/native) from \`docs/v3/openapi3.yaml\` on frain-dev/convoy main. Hand-written webhook verify (\`src/main/java/com/getconvoy/webhook/\`) is untouched by the sync script."
120+
echo "Opened PR for $BRANCH" >> "$GITHUB_STEP_SUMMARY"
121+
else
122+
echo "Updated existing PR #$existing" >> "$GITHUB_STEP_SUMMARY"
123+
fi

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ bin/
2323
local.properties
2424
*.gpg
2525
*.asc
26+
.cache/

‎README.md‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,17 @@
11
# Convoy Java SDK
22

3-
Official Convoy SDK for Java.
4-
5-
> Status: this initial release provides **webhook signature verification**. The
6-
> generated API client will follow once the OpenAPI spec covers the full API
7-
> surface.
3+
Official Convoy SDK for Java: **webhook signature verification** (hand-written)
4+
and an **API client** generated from Convoy's OpenAPI spec via
5+
[OpenAPI Generator](https://openapi-generator.tech/) (java, `native` library —
6+
JDK `java.net.http`, Jackson).
87

98
## Install
109

1110
Gradle (Kotlin DSL):
1211

1312
```kotlin
1413
dependencies {
15-
implementation("com.getconvoy:convoy:0.1.0")
14+
implementation("com.getconvoy:convoy:0.2.0")
1615
}
1716
```
1817

@@ -22,10 +21,32 @@ Maven:
2221
<dependency>
2322
<groupId>com.getconvoy</groupId>
2423
<artifactId>convoy</artifactId>
25-
<version>0.1.0</version>
24+
<version>0.2.0</version>
2625
</dependency>
2726
```
2827

28+
## Use the API client
29+
30+
```java
31+
import com.getconvoy.api.EventsApi;
32+
import com.getconvoy.client.ApiClient;
33+
import com.getconvoy.models.ModelsCreateEvent;
34+
35+
import java.util.Map;
36+
37+
ApiClient client = new ApiClient();
38+
// Default base URI is https://us.getconvoy.cloud/api; point elsewhere for
39+
// EU cloud or self-hosted instances.
40+
client.updateBaseUri("https://us.getconvoy.cloud/api");
41+
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + apiKey));
42+
43+
EventsApi events = new EventsApi(client);
44+
events.createEndpointEvent("project-id", new ModelsCreateEvent()
45+
.endpointId("endpoint-id")
46+
.eventType("invoice.paid")
47+
.data(Map.of("amount", 100, "currency", "USD")));
48+
```
49+
2950
## Verify webhook signatures
3051

3152
Verify with the raw request body, before parsing it. `verify` returns `true`
@@ -64,6 +85,20 @@ new Webhook("endpoint-secret", "SHA512", "base64", 300);
6485
Tests verify against `signature-vectors.json`, a shared cross-SDK vector set
6586
generated from the server signing code so every Convoy SDK verifies identically.
6687

88+
### Regenerating the API client
89+
90+
The client (`com.getconvoy.api`, `com.getconvoy.client`, `com.getconvoy.models`)
91+
is generated; do not edit it by hand. The hand-written verify package
92+
(`com.getconvoy.webhook`) is never touched by generation.
93+
94+
CI on `frain-dev/convoy` dispatches `sdk_generation.yaml` when OpenAPI
95+
artifacts change. Locally:
96+
97+
```bash
98+
./scripts/generate.sh # requires java 17+, curl, rsync
99+
./gradlew test
100+
```
101+
67102
## License
68103

69104
[MIT](LICENSE)

‎build.gradle.kts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ plugins {
55
}
66

77
group = "com.getconvoy"
8-
version = "0.1.0"
9-
description = "Convoy SDK for Java. Currently provides webhook signature verification."
8+
version = "0.2.0"
9+
description = "Convoy SDK for Java: webhook signature verification and an OpenAPI-generated API client."
1010

1111
repositories {
1212
mavenCentral()
@@ -21,6 +21,16 @@ java {
2121
}
2222

2323
dependencies {
24+
// Generated API client (com.getconvoy.{api,client,models}); versions must
25+
// match what OpenAPI Generator (pinned in scripts/generate.sh) targets.
26+
implementation("com.google.code.findbugs:jsr305:3.0.2")
27+
implementation("com.fasterxml.jackson.core:jackson-core:2.21.1")
28+
implementation("com.fasterxml.jackson.core:jackson-annotations:2.21")
29+
implementation("com.fasterxml.jackson.core:jackson-databind:2.21.1")
30+
implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.21.1")
31+
implementation("org.openapitools:jackson-databind-nullable:0.2.10")
32+
implementation("jakarta.annotation:jakarta.annotation-api:2.1.1")
33+
2434
testImplementation(platform("org.junit:junit-bom:5.11.3"))
2535
testImplementation("org.junit.jupiter:junit-jupiter")
2636
testImplementation("com.google.code.gson:gson:2.11.0")

‎scripts/generate.sh‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
# Regenerate the API client from Convoy's OpenAPI spec with OpenAPI Generator
5+
# (java, native library), then sync it into src/main/java/com/getconvoy/
6+
# without touching the hand-written webhook verify package.
7+
#
8+
# Requires: java 17+, rsync, curl. Run from the repo root.
9+
10+
SPEC_URL="${SPEC_URL:-https://raw.githubusercontent.com/frain-dev/convoy/main/docs/v3/openapi3.yaml}"
11+
# Pin so regeneration output is reproducible; bump deliberately.
12+
GENERATOR_VERSION="7.23.0"
13+
GENERATOR_JAR="${GENERATOR_JAR:-.cache/openapi-generator-cli-${GENERATOR_VERSION}.jar}"
14+
15+
tmp="$(mktemp -d)"
16+
trap 'rm -rf "$tmp"' EXIT
17+
18+
if [ ! -f "$GENERATOR_JAR" ]; then
19+
mkdir -p "$(dirname "$GENERATOR_JAR")"
20+
curl -fsSL -o "$GENERATOR_JAR" \
21+
"https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/${GENERATOR_VERSION}/openapi-generator-cli-${GENERATOR_VERSION}.jar"
22+
fi
23+
24+
curl -fsSL "$SPEC_URL" -o "$tmp/openapi3.yaml"
25+
26+
# hideGenerationTimestamp: @Generated annotations must not embed a wall-clock
27+
# date or every regeneration diffs all 200+ files and "no diff, no PR" breaks.
28+
java -jar "$GENERATOR_JAR" generate \
29+
-i "$tmp/openapi3.yaml" \
30+
-g java \
31+
--library native \
32+
-o "$tmp/gen" \
33+
--additional-properties=groupId=com.getconvoy,artifactId=convoy,apiPackage=com.getconvoy.api,modelPackage=com.getconvoy.models,invokerPackage=com.getconvoy.client,useJakartaEe=true,hideGenerationTimestamp=true
34+
35+
# Mirror only the three generated packages. The hand-written verify package
36+
# (com/getconvoy/webhook) is a sibling and is never created or removed here.
37+
# --delete keeps each generated package an exact mirror of generator output.
38+
for pkg in api client models; do
39+
rsync -a --delete "$tmp/gen/src/main/java/com/getconvoy/$pkg/" \
40+
"src/main/java/com/getconvoy/$pkg/"
41+
done
42+
43+
echo "Generated client synced into src/main/java/com/getconvoy/{api,client,models}"

0 commit comments

Comments
 (0)