Skip to content

openapi31: support 3.1+ reference metadata overrides #1215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlexanderWangY wants to merge 1 commit into
base: master
Choose a base branch
from
Open

openapi31: support 3.1+ reference metadata overrides #1215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 32 additions & 5 deletions .github/docs/openapi3.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,9 @@ type CallbackRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Callback
Expand Down Expand Up @@ -766,6 +769,9 @@ type ExampleRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Example
Expand Down Expand Up @@ -1017,6 +1023,9 @@ type HeaderRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Header
Expand Down Expand Up @@ -1269,6 +1278,9 @@ type LinkRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Link
Expand Down Expand Up @@ -1824,6 +1836,9 @@ type ParameterRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Parameter
Expand Down Expand Up @@ -2093,12 +2108,15 @@ func URIMapCache(reader ReadFromURIFunc) ReadFromURIFunc
documents.

type Ref struct {
Ref string `json:"$ref" yaml:"$ref"`
Extensions map[string]any `json:"-" yaml:"-"`
Origin *Origin `json:"-" yaml:"-"`
Ref string `json:"$ref" yaml:"$ref"`
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`
Extensions map[string]any `json:"-" yaml:"-"`
Origin *Origin `json:"-" yaml:"-"`
}
Ref is specified by OpenAPI/Swagger 3.0 standard. See
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object
Ref represents the common fields of an OpenAPI Reference Object.
Summary and Description are supported by OpenAPI 3.1 and later. See
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#reference-object

func (x Ref) MarshalJSON() ([]byte, error)
MarshalJSON returns the JSON encoding of Ref.
Expand Down Expand Up @@ -2187,6 +2205,9 @@ type RequestBodyRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *RequestBody
Expand Down Expand Up @@ -2302,6 +2323,9 @@ type ResponseRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *Response
Expand Down Expand Up @@ -3055,6 +3079,9 @@ type SecuritySchemeRef struct {
// are allowed by the openapi spec.
Extensions map[string]any
Origin *Origin `json:"-" yaml:"-"`
// Reference Object summary and description are supported in OpenAPI 3.1+.
Summary *string `json:"summary,omitempty" yaml:"summary,omitempty"`
Description *string `json:"description,omitempty" yaml:"description,omitempty"`

Ref string
Value *SecurityScheme
Expand Down
15 changes: 12 additions & 3 deletions openapi3/issue513_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ components:
}
}

func TestIssue513KOMixesRefAlongWithOtherFieldsDisallowed(t *testing.T) {
func TestIssue513ReferenceDescriptionIsVersionAware(t *testing.T) {
spec := `
openapi: "3.0.3"
info:
Expand All @@ -189,7 +189,7 @@ paths:
summary: Delete something
responses:
200:
description: A sibling field that the spec says is ignored
description: Reference description
$ref: '#/components/responses/SomeResponseBody'
components:
responses:
Expand All @@ -216,7 +216,16 @@ components:
doc, err := sl.LoadFromData([]byte(strings.ReplaceAll(spec, "3.0.3", majmin)))
require.NoError(t, err)
err = doc.Validate(sl.Context)
require.ErrorContains(t, err, `extra sibling fields: [description]`)
if majmin == "3.0" {
require.ErrorContains(t, err, `extra sibling fields: [description]`)
return
}
require.NoError(t, err)

response := doc.Paths.Value("/v1/operation").Delete.Responses.Status(200)
require.NotNil(t, response.Value)
require.NotNil(t, response.Value.Description)
require.Equal(t, "Reference description", *response.Value.Description)
})
}
}
Expand Down
Loading
Loading