OptionalextensionHow to combine a document-root x-* extension's value across inputs,
keyed by extension name and shaped to mirror that value's own JSON
structure (proposal 48, generalising issue #60).
An extension not mentioned here -- the default -- keeps this library's
historical behaviour: the first input that declares it wins, unchanged.
Only the document root is covered; x-* fields elsewhere (info, tags,
path items, components) are not reached by this option, because none of
those locations combines two inputs' values by a policy the way the root
does -- see ExtensionMergeNode for the full design.
OptionalexternalDocuments this merge may need to pull individual components out of, keyed by the same opaque identity described on SingleMergeInputBase.sourceIdentity (issue #10).
Unlike an input, a document here never contributes paths, webhooks,
info, security, tags or anything else to the output on its own --
only the specific components a $ref elsewhere in the merge actually asks
for are pulled in (and, transitively, whatever those components' own
references need), deduplicated against the rest of the output exactly like
any other component. A document listed here that nothing ends up
referencing contributes nothing at all.
Loading these (from disk, or over the network) is entirely the caller's
job -- by the time this reaches merge(), every document is already an
in-memory OpenApiDocument and merging proceeds synchronously, same as
always.
OptionalinfoOverride fields of the merged info object (issue #102).
info is otherwise taken from the first input, so a merged document is
titled after whichever service happens to be listed first -- misleading for
an aggregate API that is none of its inputs.
Merged field by field, so overriding only title does not require
restating the required version. Applied after description appending, so
an explicit description wins over the appended one.
OptionalpruneDrop components that nothing in the merged document references (issue #94).
Defaults to false. Off by default because pruning is destructive and this
library has always preserved every component it was given: a document may
carry definitions referenced only from outside it, and silently deleting
those would be a worse failure than carrying a few unused ones.
Turn it on when operationSelection is removing operations and you expect
the schemas only those operations used to go with them. Reachability is
computed from the surviving document, so a component still used by another
endpoint is kept.
OptionalsecurityHow components.securitySchemes is combined across inputs (issue #33).
Defaults to 'merge'. Unlike ServersStrategy, whose default keeps
the historical first-wins behaviour, this one changes it: first-wins here
produced documents whose operations required a scheme the document did not
define, which is a defect rather than a preference.
See SecuritySchemesStrategy for the three values and the case each one serves.
OptionalserversHow to combine the top-level servers array. Defaults to 'first'.
See ServersStrategy for why that is the default (issue #4).
Document-level options for a merge.
Deliberately a single bag passed as
merge()'s second argument rather than per-input fields. Everything in here concerns the output document, so a per-input value would raise a question with no good answer: which input wins when two of them disagree about a property the output has only one of?Optional in every position, and every default reproduces the behaviour that existed before the option did, so
merge(inputs)is unchanged.