Merge required keys of untagged embedded structs into the parent

[seanogdev]

Changes

• The required keys of an untagged embedded struct are now required in the parent. Before, only its properties merged into the parent.
• An embed key is required in the parent only when encoding/json uses that embed's field for the key:
  • The field at the smallest depth wins.
  • At the same depth, a key with more than one field is dropped, unless exactly one of them has a tag.
  • A parent field with the same key shadows it, also a field with {omitdoc}.
• A pointer embed gives only its explicit {required} keys, because encoding/json writes none of its fields when it is nil.
• This also applies with infer-required off, so the explicit {required} keys of an embed are now required in the parent.
• Program keeps the JSON keys of each struct: smallest depth, field count and tag count. A parent applies the rule from these keys and does not parse its embeds again.

Files changed

docparse/

• find.go: mergeEmbeds and the key helpers, out of GetReference
• docparse.go: jsonKeys on Program
• jsonschema.go: shared fieldDoc fallback

doc/

• syntax.markdown: required keys of embedded structs

testdata/openapi2/src/embed-required/

• in.go: value, pointer, clash, depth, tag, {omitdoc} and nested embeds
• test.conf: comment added
• want.yaml, want3.yaml: expected OpenAPI 2 and 3 output

testdata/openapi2/src/embed-required-explicit/

• in.go: explicit {required} in value and pointer embeds
• want.yaml, want3.yaml: expected output with infer-required off

Focus areas

• docparse/find.go
  • Only required uses the encoding/json rule. properties still merge with the first embed winning, so a key that encoding/json drops still shows in properties.
  • Output changes for users without infer-required who put {required} on embed fields.

Screenshots

[coveralls]

Coverage Report for CI Build 36029644648

Coverage decreased (-0.3%) to 57.488%

Details

• Coverage decreased (-0.3%) from the base build.
• Patch coverage: 47 uncovered changes across 1 file (45 of 92 lines covered, 48.91%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
docparse/find.go	84	37	44.05%
Total (3 files)	92	45	48.91%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	2898
Covered Lines:	1666
Line Coverage:	57.49%
Coverage Strength:	34.88 hits per line

---

💛 - Coveralls

[rafaeljusto]

🚀