Purpose: OpenAPI specs are the documentation that API consumers use to generate their own clients. If the OpenAPI spec doesn't match what the server actually does, consumers will write broken integrations. This plan ensures the OpenAPI output is 100% consistent with the other 3 generators.
Output: OpenAPI generator producing accurate schemas that match actual server/client behavior.
<execution_context> @/Users/sebastienmelki/.claude/get-shit-done/workflows/execute-plan.md @/Users/sebastienmelki/.claude/get-shit-done/templates/summary.md </execution_context>
Fix the default error response schema:
In buildResponses() function (around line 416-447), replace the inline error schema construction:
CURRENT (WRONG):
errorProps := orderedmap.New[string, *base.SchemaProxy]()
errorProps.Set("error", base.CreateSchemaProxy(&base.Schema{Type: []string{"string"}}))
errorProps.Set("code", base.CreateSchemaProxy(&base.Schema{Type: []string{"integer"}}))
errorSchema := base.CreateSchemaProxy(&base.Schema{Type: []string{"object"}, Properties: errorProps})CORRECT:
Replace with a schema that has a single message field of type string, matching the sebufhttp.Error proto definition. Better yet, create an Error component schema in the components section (like ValidationError already has a component reference) and reference it:
errorSchema := base.CreateSchemaProxyRef("#/components/schemas/Error")Then ensure the Error schema is defined in components/schemas with the correct structure: { type: "object", properties: { message: { type: "string" } } }.
Check where ValidationError is added to components/schemas and follow the same pattern for Error. Look at buildComponentSchemas() or similar function. If ValidationError is defined there, add Error alongside it.
Also verify the ValidationError schema is correct:
- It should have a
violationsarray field - Each violation should have
fieldPath(string),constraintId(string),message(string) -- using protojson camelCase names - Compare with the actual proto definition in
proto/sebuf/http/
Read proto/sebuf/http/ proto files to find the exact Error and ValidationError proto definitions and ensure OpenAPI schemas match exactly.
After fixing, run make lint-fix.
UPDATE_GOLDEN=1 go test ./internal/openapiv3/ -count=1 to update golden files. Run go test ./internal/openapiv3/ -count=1 to confirm all pass. Inspect a golden YAML file to verify the default error response now has { message: { type: string } } instead of { error: { type: string }, code: { type: integer } }.
message field (type string) matching the actual sebufhttp.Error proto definition. ValidationError schema is verified correct with violations array. Both reference component schemas instead of inline definitions.
1. int64/uint64 type mapping
Read protoTypeToOpenAPISchema (or equivalent) in types.go. Per the proto3 JSON spec, int64/uint64/sint64/sfixed64/fixed64 serialize as JSON strings. The OpenAPI schema for these fields should be:
type: string
format: int64 # (or uint64, etc.)NOT:
type: integer
format: int64If currently mapped as integer, change to string with the appropriate format. This matches the protojson behavior and the TS client's string type for int64.
2. Query parameter type mapping Verify query parameters in OpenAPI specs have the correct types:
- string params:
{ type: string } - int32 params:
{ type: integer, format: int32 } - int64 params:
{ type: string, format: int64 }(query params are URL strings, and for int64 the value is a numeric string) - uint64 params:
{ type: string, format: uint64 } - bool params:
{ type: boolean } - float params:
{ type: number, format: float } - double params:
{ type: number, format: double }
Actually, for query parameters specifically: the query string always carries string values. But OpenAPI convention is to declare the parameter's logical type. For int64/uint64, since the JSON spec says they're strings, OpenAPI should type them as string with format. For int32/bool/float/double, OpenAPI convention uses the logical type (integer/boolean/number) since JavaScript can handle them. Verify consistency.
3. Enum type mapping Verify enum fields in OpenAPI schemas use:
type: string
enum: ["VALUE_NAME_1", "VALUE_NAME_2"]Matching protojson's enum-as-string behavior. Ensure the enum values are the proto enum value names (e.g., RESOURCE_STATUS_ACTIVE), not numeric values.
4. Optional field mapping Verify optional fields are NOT marked as required in OpenAPI schemas and have correct nullability representation.
5. Map field mapping Verify map fields are represented as:
type: object
additionalProperties:
type: <value-type>6. Repeated field mapping Verify repeated fields are represented as:
type: array
items:
type: <element-type>7. Path parameter definitions
Verify path parameters are defined with in: path, required: true, and correct type. All path params are strings.
8. Response Content-Type
After 03-02 fixes, the server sets Content-Type on responses. Verify OpenAPI specs document the correct response content types. Currently they only show application/json. If the server supports protobuf responses, consider adding application/x-protobuf as an alternative response content type. However, this may be overkill for this phase -- at minimum ensure application/json is correctly documented.
After all fixes, run make lint-fix.
UPDATE_GOLDEN=1 go test ./internal/openapiv3/ -count=1 to update golden files. Run go test ./internal/openapiv3/ -count=1 to confirm all pass. Inspect golden files to verify int64 fields are type: string, format: int64. Run make lint-fix.
type: string, format: int64/uint64. Enums are type: string with string enum values. Query parameters, path parameters, and body schemas are all consistent with actual server behavior. All openapiv3 tests pass.
<success_criteria>
- OpenAPI error schemas match actual proto error definitions exactly
- int64/uint64 fields documented as string type with format, matching protojson spec
- All parameter types (query, path, header) match what clients send and server expects
- Enum, optional, map, and repeated fields correctly represented
- All openapiv3 golden file tests pass </success_criteria>