From f79347251609034b7e6e98ed4d92bcaa623b0f1f Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 1 Dec 2021 19:29:18 +0100 Subject: [PATCH 1/6] Add x-internal --- openapi/generator.go | 1 + openapi/operation.go | 1 + openapi/spec.go | 2 ++ 3 files changed, 4 insertions(+) diff --git a/openapi/generator.go b/openapi/generator.go index e61c64f..17fa14e 100644 --- a/openapi/generator.go +++ b/openapi/generator.go @@ -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) diff --git a/openapi/operation.go b/openapi/operation.go index 61aa607..306900f 100644 --- a/openapi/operation.go +++ b/openapi/operation.go @@ -14,6 +14,7 @@ type OperationInfo struct { Responses []*OperationResponse Security []*SecurityRequirement XCodeSamples []*XCodeSample + XInternal bool } // ResponseHeader represents a single header that diff --git a/openapi/spec.go b/openapi/spec.go index 972cb90..64e6c24 100644 --- a/openapi/spec.go +++ b/openapi/spec.go @@ -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. @@ -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"` } // MarshalYAML implements yaml.Marshaler for Operation. From 1edbb1dbcb58ea11921e8965afefcf13ac6061f5 Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 1 Dec 2021 19:40:17 +0100 Subject: [PATCH 2/6] Add fizz.XInternal helper --- README.md | 3 +++ fizz.go | 7 +++++++ fizz_test.go | 1 + testdata/spec.json | 3 ++- testdata/spec.yaml | 1 + 5 files changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e389ff..95b71f9 100644 --- a/README.md +++ b/README.md @@ -110,6 +110,9 @@ fizz.WithoutSecurity() // Add a Code Sample to the operation. fizz.XCodeSample(codeSample *XCodeSample) + +// Mark the operation as internal or external. +fizz.XInternal(isInternal bool) ``` **NOTES:** diff --git a/fizz.go b/fizz.go index 813b44a..e9fd8ad 100644 --- a/fizz.go +++ b/fizz.go @@ -383,6 +383,13 @@ func WithoutSecurity() func(*openapi.OperationInfo) { } } +// XInternal marks the operation as internal or external. +func XInternal(isInternal bool) func(*openapi.OperationInfo) { + return func(o *openapi.OperationInfo) { + o.XInternal = isInternal + } +} + // 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) { diff --git a/fizz_test.go b/fizz_test.go index 531e0e5..ffe2e8a 100644 --- a/fizz_test.go +++ b/fizz_test.go @@ -273,6 +273,7 @@ func TestSpecHandler(t *testing.T) { }), // Explicit override for SecurityRequirement (allow-all) WithoutSecurity(), + XInternal(true), }, tonic.Handler(func(c *gin.Context) error { return nil diff --git a/testdata/spec.json b/testdata/spec.json index ab8da3c..23bb008 100644 --- a/testdata/spec.json +++ b/testdata/spec.json @@ -104,7 +104,8 @@ "source": "curl http://0.0.0.0:8080" } ], - "security": [] + "security": [], + "x-internal": true } }, "/test/{a}/{b}": { diff --git a/testdata/spec.yaml b/testdata/spec.yaml index f548713..520c377 100644 --- a/testdata/spec.yaml +++ b/testdata/spec.yaml @@ -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 From 97570a3e58b7c5261a204da0d440ac2e306c8a92 Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 22 Dec 2021 17:22:41 +0100 Subject: [PATCH 3/6] Drop isInternal argument --- fizz.go | 4 ++-- fizz_test.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/fizz.go b/fizz.go index e9fd8ad..18f19fe 100644 --- a/fizz.go +++ b/fizz.go @@ -384,9 +384,9 @@ func WithoutSecurity() func(*openapi.OperationInfo) { } // XInternal marks the operation as internal or external. -func XInternal(isInternal bool) func(*openapi.OperationInfo) { +func XInternal() func(*openapi.OperationInfo) { return func(o *openapi.OperationInfo) { - o.XInternal = isInternal + o.XInternal = true } } diff --git a/fizz_test.go b/fizz_test.go index ffe2e8a..2050d82 100644 --- a/fizz_test.go +++ b/fizz_test.go @@ -273,7 +273,7 @@ func TestSpecHandler(t *testing.T) { }), // Explicit override for SecurityRequirement (allow-all) WithoutSecurity(), - XInternal(true), + XInternal(), }, tonic.Handler(func(c *gin.Context) error { return nil From 5a231927e522884dfe8f648c5801a714afbcba10 Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 22 Dec 2021 17:35:07 +0100 Subject: [PATCH 4/6] Fix docs --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 95b71f9..07c07a0 100644 --- a/README.md +++ b/README.md @@ -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. +fizz.XInternal() ``` **NOTES:** From 3dd184e72502bd0595aa95c89217a4088b040a0b Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 22 Dec 2021 17:37:07 +0100 Subject: [PATCH 5/6] Fix docstring --- fizz.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fizz.go b/fizz.go index 18f19fe..e28efaa 100644 --- a/fizz.go +++ b/fizz.go @@ -383,7 +383,7 @@ func WithoutSecurity() func(*openapi.OperationInfo) { } } -// XInternal marks the operation as internal or external. +// XInternal marks the operation as internal. func XInternal() func(*openapi.OperationInfo) { return func(o *openapi.OperationInfo) { o.XInternal = true From 075f6067664b3c5aeadfb0ce83ff048e88e96694 Mon Sep 17 00:00:00 2001 From: Niko Date: Wed, 22 Dec 2021 17:43:11 +0100 Subject: [PATCH 6/6] Add quick note --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 07c07a0..0294c2d 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ fizz.WithoutSecurity() // Add a Code Sample to the operation. fizz.XCodeSample(codeSample *XCodeSample) -// Mark the operation as internal. +// 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() ```