Associate OpenAPI elements with the originating line and column in the YAML specification #986
Description
Hi all,
As the maintainer of oasdiff which relies on kin-openapi to report changes in OpenAPI specs, I have a requirement from oasdiff users to be able to correlate the breaking-change messages with the originating lines in the YAML specifications.
I created a small proof-of-concept which achieves this as follows:
- Extend yaml.v3 to add line and column numbers of each YAML element to the unmarshalled interfaces
- Extend kin-openapi UnmarshalJSON functions to read these new elements into the OpenAPI structs (T, Paths, PathItem...)
For example, here's a proposal for the extended T struct:
// Location points to a line and column in the originating YAML file
type Location struct {
Line int
Col int
}
// Origin provides information about the locations of an element and its fields in the originating YAML file
type Origin struct {
Element *Location
Fields map[string]*Location
}
// T is the root of an OpenAPI v3 document
// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#openapi-object
type T struct {
Extensions map[string]any `json:"-" yaml:"-"`
Origin *Origin
OpenAPI string `json:"openapi" yaml:"openapi"` // Required
Components *Components `json:"components,omitempty" yaml:"components,omitempty"`
Info *Info `json:"info" yaml:"info"` // Required
Paths *Paths `json:"paths" yaml:"paths"` // Required
Security SecurityRequirements `json:"security,omitempty" yaml:"security,omitempty"`
Servers Servers `json:"servers,omitempty" yaml:"servers,omitempty"`
Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
visited visitedComponent
url *url.URL
}
Before moving forward, I'd like to collect some feedback:
- Do you see value in this feature?
- Do you have comments about the proposed solution?
- Anything else?
Thanks,
Reuven