From 408c6fc97b357135112c8af249436eca303ec154 Mon Sep 17 00:00:00 2001
From: nikicc <niko@viaduct.ai>
Date: Wed, 22 Dec 2021 17:47:40 +0100
Subject: [PATCH] Add x-internal (#64)

feat: add support for the x-internal flag
---
 README.md            | 3 +++
 fizz.go              | 7 +++++++
 fizz_test.go         | 1 +
 openapi/generator.go | 1 +
 openapi/operation.go | 1 +
 openapi/spec.go      | 2 ++
 testdata/spec.json   | 3 ++-
 testdata/spec.yaml   | 1 +
 8 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2e389ff..0294c2d 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. The x-internal flag is interpreted by third-party tools and it only impacts the visual documentation rendering.
+fizz.XInternal()
 ```
 
 **NOTES:**
diff --git a/fizz.go b/fizz.go
index 813b44a..e28efaa 100644
--- a/fizz.go
+++ b/fizz.go
@@ -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) {
diff --git a/fizz_test.go b/fizz_test.go
index 531e0e5..2050d82 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(),
 		},
 		tonic.Handler(func(c *gin.Context) error {
 			return nil
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.
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