Add x-internal #64
Add x-internal #64
Conversation
|
@wI2L wdyt? |
fizz.go
Outdated
| @@ -360,6 +360,13 @@ func XCodeSample(cs *openapi.XCodeSample) func(*openapi.OperationInfo) { | |||
| } | |||
| } | |||
|
|
|||
| // XInternal marks the operation as internal or external. | |||
| func XInternal(isInternal bool) func(*openapi.OperationInfo) { | |||
There was a problem hiding this comment.
Thought we might not need an argument, since the default behavior is external (internal: false), so the option func could be used as simply as XInternal().
There was a problem hiding this comment.
Agreed. I removed it now.
|
I merged some old pending PR, you need to rebase from the master branch. |
| @@ -194,6 +194,7 @@ type Operation 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"` | |||
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Agreed, lets keep the omitempty flag then.
fizz.go
Outdated
| @@ -360,6 +360,13 @@ func XCodeSample(cs *openapi.XCodeSample) func(*openapi.OperationInfo) { | |||
| } | |||
| } | |||
|
|
|||
| // XInternal marks the operation as internal or external. | |||
| func XInternal(isInternal bool) func(*openapi.OperationInfo) { | |||
There was a problem hiding this comment.
Agreed. I removed it now.
| @@ -194,6 +194,7 @@ type Operation 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"` | |||
There was a problem hiding this comment.
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?
Codecov Report
@@ Coverage Diff @@
## master #64 +/- ##
==========================================
+ Coverage 95.17% 95.18% +0.01%
==========================================
Files 7 7
Lines 953 956 +3
==========================================
+ Hits 907 910 +3
Misses 30 30
Partials 16 16
Continue to review full report at Codecov.
|
README.md
Outdated
| @@ -111,8 +111,8 @@ fizz.WithoutSecurity() | |||
| // Add a Code Sample to the operation. | |||
| fizz.XCodeSample(codeSample *XCodeSample) | |||
|
|
|||
| // Mark the operation as internal or external. | |||
| fizz.XInternal(isInternal bool) | |||
| // Mark the operation as internal. | |||
There was a problem hiding this comment.
Since this is an extension, it might be beneficial for the readers to indicate that this is interpreted by third-party tools, and the impact is only on visual rendering. No need for an essai :) just a quick note.
There was a problem hiding this comment.
Yes, that can be helpful. Added a quick note now.
This PR adds the support for marking the endpoints as
x-internal, which is a mechanism for hiding endpoints in the rendered docs.Background
Some docs rendering tools (e.g. ReDoc and Elements) support the functionality of the endpoints to be hidden from the docs, if they are marked as
x-internal. The changes here add the support forx-internal.