Skip to content
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

Add x-internal #64

Merged
merged 6 commits into from
Dec 22, 2021
Merged

Add x-internal #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f793472
Add x-internal
nikicc Dec 1, 2021
1edbb1d
Add fizz.XInternal helper
nikicc Dec 1, 2021
97570a3
Drop isInternal argument
nikicc Dec 22, 2021
5a23192
Fix docs
nikicc Dec 22, 2021
3dd184e
Fix docstring
nikicc Dec 22, 2021
075f606
Add quick note
nikicc Dec 22, 2021
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
3 changes: 3 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,9 @@ fizz.WithoutSecurity()

// Add a Code Sample to the operation.
fizz.XCodeSample(codeSample *XCodeSample)

// Mark the operation as internal. The x-internal flag is interpreted by third-party tools and it only impacts the visual documentation rendering.
fizz.XInternal()
```

**NOTES:**
Expand Down
7 changes: 7 additions & 0 deletions fizz.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,6 +383,13 @@ func WithoutSecurity() func(*openapi.OperationInfo) {
}
}

// XInternal marks the operation as internal.
func XInternal() func(*openapi.OperationInfo) {
return func(o *openapi.OperationInfo) {
o.XInternal = true
}
}

// OperationFromContext returns the OpenAPI operation from
// the givent Gin context or an error if none is found.
func OperationFromContext(c *gin.Context) (*openapi.Operation, error) {
Expand Down
1 change: 1 addition & 0 deletions fizz_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,7 @@ func TestSpecHandler(t *testing.T) {
}),
// Explicit override for SecurityRequirement (allow-all)
WithoutSecurity(),
XInternal(),
},
tonic.Handler(func(c *gin.Context) error {
return nil
Expand Down
1 change: 1 addition & 0 deletions openapi/generator.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ func (g *Generator) AddOperation(path, method, tag string, in, out reflect.Type,
op.Responses = make(Responses)
op.XCodeSamples = info.XCodeSamples
op.Security = info.Security
op.XInternal = info.XInternal
}
if tag != "" {
op.Tags = append(op.Tags, tag)
Expand Down
1 change: 1 addition & 0 deletions openapi/operation.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ type OperationInfo struct {
Responses []*OperationResponse
Security []*SecurityRequirement
XCodeSamples []*XCodeSample
XInternal bool
}

// ResponseHeader represents a single header that
Expand Down
2 changes: 2 additions & 0 deletions openapi/spec.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,7 @@ type Operation struct {
Servers []*Server `json:"servers,omitempty" yaml:"servers,omitempty"`
Security []*SecurityRequirement `json:"security" yaml:"security"`
XCodeSamples []*XCodeSample `json:"x-codeSamples,omitempty" yaml:"x-codeSamples,omitempty"`
XInternal bool `json:"x-internal,omitempty" yaml:"x-internal,omitempty"`
}

// A workaround for missing omitnil functionality.
Expand All @@ -213,6 +214,7 @@ type operationNilOmitted struct {
Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
Servers []*Server `json:"servers,omitempty" yaml:"servers,omitempty"`
XCodeSamples []*XCodeSample `json:"x-codeSamples,omitempty" yaml:"x-codeSamples,omitempty"`
XInternal bool `json:"x-internal,omitempty" yaml:"x-internal,omitempty"`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does the spec say about it ? Is it preferable if its omitted when its false (external), or should it be present for clarity and/or compatibility with the rendering interfaces ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. Can't find anything really 🙈 Maybe it's a bit unclear as this is an extension, so I'm not sure it's covered in the spec?

Given that this is an extension, I'm leaning towards not showing x-internal: false (which should be the current behaviour) to not "pollute" the spec with default values of extensions. WDYT?

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, lets keep the omitempty flag then.

}

// MarshalYAML implements yaml.Marshaler for Operation.
Expand Down
3 changes: 2 additions & 1 deletion testdata/spec.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,8 @@
"source": "curl http://0.0.0.0:8080"
}
],
"security": []
"security": [],
"x-internal": true
}
},
"/test/{a}/{b}": {
Expand Down
1 change: 1 addition & 0 deletions testdata/spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ paths:
label: v4.4
source: curl http://0.0.0.0:8080
security: []
x-internal: true
/test/{a}/{b}:
get:
operationId: GetTest2
Expand Down