feat: merge duplicate status code responses into oneOf

[oscarbc96]

Summary

• When two responses share the same HTTP status code and content type (e.g., two 200 application/json responses with different structs), the second silently overwrites the first in the upstream openapi-go library
• Fixes this by intercepting responses in operationContextImpl.build() before calling AddRespStructure, grouping duplicates by (HTTPStatus, ContentType), and merging groups with >1 entry into a single oneOf response via jsonschema.OneOf() — a helper already supported upstream
• Includes test coverage with golden files for both OpenAPI 3.0 and 3.1

What's included

• operation.go — new mergeResponses helper + updated build():
  • Groups responses by (HTTPStatus, ContentType) key
  • Groups with 1 entry: kept as-is
  • Groups with >1 entry: combined via jsonschema.OneOf(s1, s2, ...), first entry's description preserved, single ContentUnit produced
  • Insertion order preserved
• router_test.go — new "Duplicate Status Code Responses" test case that registers two 200 responses with different structs on the same endpoint
• testdata/duplicate_status_code_responses_3.yaml — golden file for OpenAPI 3.0
• testdata/duplicate_status_code_responses_31.yaml — golden file for OpenAPI 3.1

Generated output

Both golden files confirm the oneOf output:

responses:
  "200":
    content:
      application/json:
        schema:
          oneOf:
          - $ref: '#/components/schemas/SpecTestSuccessA'
          - $ref: '#/components/schemas/SpecTestSuccessB'
    description: OK

How to test

This was developed using Claude Code. To test before this is merged, you can use Go module replacements in your go.mod:

replace github.com/oaswrap/spec => github.com/oscarbc96/spec v0.0.0-20260301171053-d3ae53d

🤖 Generated with Claude Code