Add x-internal (#64)

feat: add support for the x-internal flag

Author: nikicc

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:**

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) {

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

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)

openapi/operation.go

@@ -14,6 +14,7 @@ type OperationInfo struct {
 	Responses         []*OperationResponse
 	Security          []*SecurityRequirement
 	XCodeSamples      []*XCodeSample
+	XInternal         bool
 }
 
 // ResponseHeader represents a single header that

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.

testdata/spec.json

@@ -104,7 +104,8 @@
                         "source": "curl http://0.0.0.0:8080"
                     }
                 ],
-                "security": []
+                "security": [],
+                "x-internal": true
             }
         },
         "/test/{a}/{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