Add BindJSONBody to bind the request body value kin-openapi validated (#165)

* Add BindJSONBody to bind the request body value kin-openapi validated

Strict net/http servers decode a JSON request body a second time after the
validation middleware has validated it, and encoding/json matches member
names case-insensitively, so a body such as {"role":"user","ROLE":"admin"}
passes validation as role=user and reaches the handler as Role="admin",
bypassing the schema's constraints.

kin-openapi v0.151.0 added openapi3filter.Options.KeepValidatedValue, which
leaves the decoded and validated value on the request body behind a
ValidatedValue() any method. BindJSONBody binds that value into the request
struct when it is present, and otherwise (or when the value does not fit the
destination) falls back to json.NewDecoder(r.Body).Decode as before, so
error behaviour is unchanged.

BindJSONValue does the binding by reflection, following encoding/json's rules
for struct tags, embedded struct promotion, json.Unmarshaler and
encoding.TextUnmarshaler, base64 []byte and float64 for any, with exact
member-name matching. The destination is left untouched when binding fails.

Part of oapi-codegen/oapi-codegen#2605.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Fix lint findings in bindjson_test.go

golangci-lint flagged two things in the bindJSONAll fixture struct:

- staticcheck SA5008 on the `json:"-,"` tag. That tag is intentional: it
  names the member "-" (the encoding/json documented way to do so), and
  TestBindJSONValue_FieldCacheIsStable asserts the binder resolves it that
  way. Keep the tag and silence the check with an explanatory nolint.
- unused on the `unexported` field. The field exists so the fixture
  exercises the binder skipping unexported fields. Reference it with an
  assertion that it is never set, which both documents the intent and
  satisfies the linter.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: mromaszewicz

README.md

@@ -221,3 +221,26 @@ correct, media-type-defined behavior.
   their original precision, but the round-trip through JSON means struct
   field tags are honored (not raw Go field names).
 
+
+## Request body binding
+
+`BindJSONBody` is what strict net/http servers generated by `oapi-codegen` call
+to decode a JSON request body. When the request has passed through a validation
+middleware built on kin-openapi's `openapi3filter` with
+`Options.KeepValidatedValue` set (for example
+`nethttp-middleware.OapiRequestValidatorWithOptions`), the body carries the
+value the validator decoded and validated, and `BindJSONBody` binds that value
+into the request struct with `BindJSONValue` instead of decoding the body a
+second time.
+
+Binding follows `encoding/json`'s rules (struct tags, embedded structs,
+`json.Unmarshaler` / `encoding.TextUnmarshaler`, base64 for `[]byte`, `float64`
+for `any`), with one deliberate difference: object member names are matched to
+struct fields **exactly**, whereas `encoding/json` matches them
+case-insensitively. This closes the gap where `{"role":"user","ROLE":"admin"}`
+validates as `role: user` but a second `encoding/json` decode binds
+`Role: "admin"`.
+
+Without a validated value, or when the value cannot be bound into the
+destination type, `BindJSONBody` decodes the body with `encoding/json` exactly
+as before, so error responses are unchanged.