Bug Report: OpenAPI Code Generation Version Compatibility Issue: 3.0.2 vs 3.1.0 Causing SDK Generation Failures

[torbensen]

Bug Report

Version

svix v1.76.1

Platform

Darwin 24.4.0 Darwin Kernel Version 24.4.0

Description

OpenAPI Code Generation Version Compatibility Issue: 3.0.2 vs 3.1.0 Causing SDK Generation Failures

I tried this code:

1. Generate OpenAPI specification:

./server/generate-openapi.sh

2. Generate SDKs using the generated OpenAPI:

cp ./server/openapi.json ./codegen/lib-openapi.json
python regen_openapi.py

I expected to see this happen:

• OpenAPI specification generated successfully
• All language SDKs generated without errors
• No version compatibility issues

Instead, this happened:

First Error - Invalid Escape Sequence:

invalid escape at line 12 column 53

Error location: "pattern": "^[a-zA-Z0-9\-_.]+$" - invalid escape sequence \-

Second Error - Missing Success Responses:
After fixing the escape sequence and changing OpenAPI version from 3.0.2 to 3.1.0:

every operation must have one success response

Root Cause Analysis:
Found 3 API operations missing success response definitions:

• DELETE /api/v1/app/{app_id}/msg/{msg_id}/attempt/{attempt_id}/content (missing 204 response)
• DELETE /api/v1/app/{app_id}/msg/{msg_id}/content (missing 204 response)
• HEAD /api/v1/health (missing 200 response)

Technical Details:

1. Code generation tools expect OpenAPI 3.1.0, but generation script outputs 3.0.2 by default
2. Rust code defines operations returning StatusCode::NO_CONTENT and (StatusCode, Json<HealthReport>), but Aide framework doesn't automatically generate corresponding OpenAPI response definitions
3. This causes a mismatch between what the Rust code returns and what the OpenAPI spec documents

Questions:

1. Am I doing something wrong in my approach? Should I be using a different version or configuration?
2. What's the correct way to handle this? Should I always use OpenAPI 3.1.0 for code generation or manually add response definitions in Rust code?
3. Is there a specific workflow I should follow for generating OpenAPI specs and then generating SDKs?

Related Files:

• server/generate-openapi.sh - OpenAPI generation script
• codegen/codegen.toml - Code generation configuration
• server/svix-server/src/v1/endpoints/message.rs - Message endpoint definitions
• server/svix-server/src/v1/endpoints/attempt.rs - Attempt endpoint definitions
• server/svix-server/src/v1/endpoints/health.rs - Health check endpoint definitions

[svix-jplatte]

Hey!

So really the reason we have regen_openapi.py in this repo is for convenience - it's the script we use for updating the SDKs to a new version of the Svix Cloud OpenAPI doc. We have not been keeping the OpenAPI generation script in this repo up-to-date with the one we have for Cloud.

Could you explain what you are trying to here?