Converting a document discards its specification extensions almost everywhere. Only info keeps them.
Reproduction
swagger: "2.0"
info:
title: T
version: "1.0.0"
x-info-ext: kept?
x-root-ext: kept?
paths:
/a:
x-pathitem-ext: kept?
get:
operationId: a
x-op-ext: kept?
responses:
"200":
description: OK
x-response-ext: kept?
x-responses-ext: kept?$ oastools convert -t 3.0.3 -q spec.yaml | grep "x-.*ext"
x-info-ext: kept?One of six survives. The root document, Path Item, Operation, Response and Responses Object extensions are all discarded.
Cause
The converters build fresh target values field by field and never copy Extra. For example convertOAS2OperationToOAS3 constructs a parser.Responses from Default and Codes alone, and nothing in converter/oas2_to_oas3.go or converter/oas3_to_oas2.go mentions Extra at all.
Why it matters
Extensions are how the specification says to carry vendor data, and plenty of real specs lean on them heavily for codegen hints, rate limits and gateway configuration. A conversion that silently drops them turns a lossless-looking operation into data loss, with nothing reported.
Worth deciding at implementation time whether a downgrade should report anything for extensions that cannot be represented, or simply carry them through, since extensions are version-neutral by design.
Scope
converter/oas2_to_oas3.go, converter/oas3_to_oas2.go, and any other site building a target value from scratch. A sweep is better than fixing the positions named above one at a time: the same omission will exist wherever a value is rebuilt field by field.
Converting a document discards its specification extensions almost everywhere. Only
infokeeps them.Reproduction
One of six survives. The root document, Path Item, Operation, Response and Responses Object extensions are all discarded.
Cause
The converters build fresh target values field by field and never copy
Extra. For exampleconvertOAS2OperationToOAS3constructs aparser.ResponsesfromDefaultandCodesalone, and nothing inconverter/oas2_to_oas3.goorconverter/oas3_to_oas2.gomentionsExtraat all.Why it matters
Extensions are how the specification says to carry vendor data, and plenty of real specs lean on them heavily for codegen hints, rate limits and gateway configuration. A conversion that silently drops them turns a lossless-looking operation into data loss, with nothing reported.
Worth deciding at implementation time whether a downgrade should report anything for extensions that cannot be represented, or simply carry them through, since extensions are version-neutral by design.
Scope
converter/oas2_to_oas3.go,converter/oas3_to_oas2.go, and any other site building a target value from scratch. A sweep is better than fixing the positions named above one at a time: the same omission will exist wherever a value is rebuilt field by field.