Add explicit httpapi response specs

[swetjen]

Summary

• add httpapi.ResponseSpec and HandlerMeta.Responses for explicit multi-status and custom-media response contracts
• support optional request bodies via httpapi.Optional[Req]() and extend typed non-JSON response docs/client handling
• expand docs and tests for migration guidance, response-spec behavior, and guard/query ergonomics

Testing

• go test ./...