Merge branch 'padiazg-feature-addroute-n-buildstream'

Author: kaynetik

.gitignore

@@ -3,4 +3,5 @@
 #internal/dist/openapi.yaml
 testing_out.yaml
 ./testing_out.yaml
-internal/dist/openapi.yaml
+internal/dist/openapi.yaml
+.vscode

README.md

@@ -119,7 +119,9 @@ other parts of the system for that matter.
 To run examples, and checkout hosted documentation via Swagger UI, issue the following command:
 
 ```sh
-$ go run ./examples/*.go
+$ go run ./examples/file_output/*.go
+# or uncomment line 40 and comment line 38 in internal/dist/index.html before running:
+$ go run ./examples/stream_output/*.go
 ```
 
 And navigate to `http://localhost:3005/docs/api/` in case that you didn't change anything before running the example

build.go

@@ -38,7 +38,7 @@ func getPathFromFirstElement(cbs []ConfigBuilder) string {
 func (o *OAS) BuildDocs(conf ...ConfigBuilder) error {
 	o.initCallStackForRoutes()
 
-	yml, err := marshalToYAML(o)
+	yml, err := o.marshalToYAML()
 	if err != nil {
 		return fmt.Errorf("marshaling issue occurred: %w", err)
 	}
@@ -51,7 +51,23 @@ func (o *OAS) BuildDocs(conf ...ConfigBuilder) error {
 	return nil
 }
 
-func marshalToYAML(oas *OAS) ([]byte, error) {
+// BuildStream marshals the OAS struct to YAML and writes it to a stream.
+//
+// Returns an error if there is any.
+func (o *OAS) BuildStream(w io.Writer) error {
+	yml, err := o.marshalToYAML()
+	if err != nil {
+		return fmt.Errorf("marshaling issue occurred: %w", err)
+	}
+
+	err = writeAndFlush(yml, w)
+	if err != nil {
+		return fmt.Errorf("writing issue occurred: %w", err)
+	}
+	return nil
+}
+
+func (oas *OAS) marshalToYAML() ([]byte, error) {
 	transformedOAS := oas.transformToHybridOAS()
 
 	yml, err := yaml.Marshal(transformedOAS)

build_test.go

@@ -1,6 +1,9 @@
 package docs
 
-import "testing"
+import (
+	"bytes"
+	"testing"
+)
 
 func TestUnitBuild(t *testing.T) {
 	t.Parallel()
@@ -109,3 +112,124 @@ func TestUnitGetPathFromFirstElem(t *testing.T) {
 }
 
 // QUICK CHECK TESTS ARE COMING WITH NEXT RELEASE.
+
+func TestOAS_BuildStream(t *testing.T) {
+	tests := []struct {
+		name    string
+		oas     *OAS
+		wantW   string
+		wantErr bool
+	}{
+		{
+			name: "success",
+			oas: &OAS{
+				OASVersion: "3.0.1",
+				Info: Info{
+					Title:       "Test",
+					Description: "Test object",
+				},
+				Components: Components{
+					Component{
+						Schemas: Schemas{Schema{
+							Name: "schema_testing",
+							Properties: SchemaProperties{
+								SchemaProperty{
+									Name:        "EnumProp",
+									Type:        "enum",
+									Description: "short desc",
+									Enum:        []string{"enum", "test", "strSlc"},
+								},
+								SchemaProperty{
+									Name:        "intProp",
+									Type:        "integer",
+									Format:      "int64",
+									Description: "short desc",
+									Default:     1337,
+								},
+							},
+							XML: XMLEntry{Name: "XML entry test"},
+						}},
+						SecuritySchemes: SecuritySchemes{SecurityScheme{
+							Name: "ses_scheme_testing",
+							In:   "not empty",
+							Flows: SecurityFlows{SecurityFlow{
+								Type:    "implicit",
+								AuthURL: "http://petstore.swagger.io/oauth/dialog",
+								Scopes: SecurityScopes{
+									SecurityScope{
+										Name:        "write:pets",
+										Description: "Write to Pets",
+									},
+									SecurityScope{
+										Name:        "read:pets",
+										Description: "Read Pets",
+									},
+								},
+							}},
+						}},
+					},
+				},
+			},
+			wantErr: false,
+			wantW: `openapi: 3.0.1
+info:
+    title: Test
+    description: Test object
+    termsOfService: ""
+    contact:
+        email: ""
+    license:
+        name: ""
+        url: ""
+    version: ""
+externalDocs:
+    description: ""
+    url: ""
+servers: []
+tags: []
+paths: {}
+components:
+    schemas:
+        schema_testing:
+            $ref: ""
+            properties:
+                EnumProp:
+                    description: short desc
+                    enum:
+                        - enum
+                        - test
+                        - strSlc
+                    type: enum
+                intProp:
+                    default: 1337
+                    description: short desc
+                    format: int64
+                    type: integer
+            type: ""
+            xml:
+                name: XML entry test
+    securitySchemes:
+        ses_scheme_testing:
+            flows:
+                implicit:
+                    authorizationUrl: http://petstore.swagger.io/oauth/dialog
+                    scopes:
+                        read:pets: Read Pets
+                        write:pets: Write to Pets
+            in: not empty
+`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			w := &bytes.Buffer{}
+			if err := tt.oas.BuildStream(w); (err != nil) != tt.wantErr {
+				t.Errorf("OAS.BuildStream() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if gotW := w.String(); gotW != tt.wantW {
+				t.Errorf("OAS.BuildStream() = [%v], want {%v}", gotW, tt.wantW)
+			}
+		})
+	}
+}