Merge pull request #123 from cmars/fix/godoc-generated-embed

fix: add godoc comment to generated embed.FS

Makefile

@@ -22,6 +22,7 @@ update-deps:
 .PHONY: lint
 lint:
 	golangci-lint run -v ./...
+	(cd versionware/example; golangci-lint run -v ./...)
 
 .PHONY: lint-docker
 lint-docker:

internal/compiler/compiler.go

@@ -375,8 +375,9 @@ import "embed"
 {{ range .VersionSpecFiles -}}
 //go:embed {{ . }}
 {{ end -}}
+// Versions contains OpenAPI specs for each distinct release version.
 var Versions embed.FS
-`))
+`[1:]))
 
 // BuildAll builds all APIs in the project.
 func (c *Compiler) BuildAll(ctx context.Context) error {

versionware/example/chi/example_test.go

@@ -14,9 +14,9 @@ import (
 	metrics "github.com/slok/go-http-metrics/metrics/prometheus"
 	promware "github.com/slok/go-http-metrics/middleware"
 	promware_std "github.com/slok/go-http-metrics/middleware/std"
+
 	"github.com/snyk/vervet"
 	"github.com/snyk/vervet/versionware"
-
 	. "github.com/snyk/vervet/versionware/example"
 	"github.com/snyk/vervet/versionware/example/releases"
 	release_2021_11_01 "github.com/snyk/vervet/versionware/example/resources/things/2021-11-01"
@@ -25,7 +25,7 @@ import (
 	"github.com/snyk/vervet/versionware/example/store"
 )
 
-func ExampleChi() {
+func Example() {
 	// Set up a test HTTP server
 	var h http.Handler
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -100,7 +100,10 @@ func ExampleChi() {
 	// Observability stuff at the top-level, not part of the API
 	root.Get("/metrics", promhttp.Handler().ServeHTTP)
 	root.Get("/healthcheck", func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("OK"))
+		_, err := w.Write([]byte("OK"))
+		if err != nil {
+			panic(err)
+		}
 	})
 
 	// Do a health check

versionware/example/embed_test.go

@@ -0,0 +1,29 @@
+package example
+
+import (
+	"testing"
+
+	qt "github.com/frankban/quicktest"
+
+	"github.com/snyk/vervet"
+	"github.com/snyk/vervet/versionware/example/releases"
+)
+
+func TestEmbedding(t *testing.T) {
+	c := qt.New(t)
+
+	specs, err := vervet.LoadVersions(releases.Versions)
+	c.Assert(err, qt.IsNil)
+	c.Assert(specs, qt.HasLen, 3)
+	var versions []string
+	for i := range specs {
+		version, err := vervet.ExtensionString(specs[i].ExtensionProps, vervet.ExtSnykApiVersion)
+		c.Assert(err, qt.IsNil)
+		versions = append(versions, version)
+	}
+	c.Assert(versions, qt.ContentEquals, []string{
+		"2021-11-01~experimental",
+		"2021-11-08~experimental",
+		"2021-11-20~experimental",
+	})
+}

versionware/example/go.mod

@@ -3,6 +3,7 @@ module github.com/snyk/vervet/versionware/example
 go 1.16
 
 require (
+	github.com/frankban/quicktest v1.13.0 // indirect
 	github.com/getkin/kin-openapi v0.87.0
 	github.com/go-chi/chi/v5 v5.0.7
 	github.com/gorilla/mux v1.8.0

versionware/example/gorilla/example_test.go

@@ -12,9 +12,9 @@ import (
 	metrics "github.com/slok/go-http-metrics/metrics/prometheus"
 	promware "github.com/slok/go-http-metrics/middleware"
 	promware_std "github.com/slok/go-http-metrics/middleware/std"
+
 	"github.com/snyk/vervet"
 	"github.com/snyk/vervet/versionware"
-
 	. "github.com/snyk/vervet/versionware/example"
 	"github.com/snyk/vervet/versionware/example/releases"
 	release_2021_11_01 "github.com/snyk/vervet/versionware/example/resources/things/2021-11-01"
@@ -23,7 +23,7 @@ import (
 	"github.com/snyk/vervet/versionware/example/store"
 )
 
-func ExampleGorilla() {
+func Example() {
 	// Set up a test HTTP server
 	var h http.Handler
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -86,7 +86,10 @@ func ExampleGorilla() {
 	// Observability stuff at the top-level, not part of the API
 	root.Handle("/metrics", promhttp.Handler())
 	root.HandleFunc("/healthcheck", func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("OK"))
+		_, err := w.Write([]byte("OK"))
+		if err != nil {
+			panic(err)
+		}
 	})
 
 	// Do a health check

versionware/example/releases/embed.go

@@ -1,4 +1,3 @@
-
 package releases
 
 import "embed"
@@ -11,4 +10,5 @@ import "embed"
 //go:embed 2021-11-08~experimental/spec.yaml
 //go:embed 2021-11-20~experimental/spec.json
 //go:embed 2021-11-20~experimental/spec.yaml
+// Versions contains OpenAPI specs for each distinct release version.
 var Versions embed.FS

versionware/example/resources/things/2021-11-01/handlers.go

@@ -7,15 +7,14 @@ import (
 	"path"
 
 	"github.com/snyk/vervet"
-
 	"github.com/snyk/vervet/versionware/example/resources/things"
 	"github.com/snyk/vervet/versionware/example/store"
 )
 
 // Version is the resource release version of handlers in this package.
 var Version = vervet.MustParseVersion("2021-11-01~experimental")
 
-// GetThing returns a request handler that uses the given data store.
+// CreateThing returns a request handler that uses the given data store.
 // It creates a new thing.
 func CreateThing(s *store.Store) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {

versionware/example/resources/things/2021-11-08/handlers.go

@@ -6,7 +6,6 @@ import (
 	"net/http"
 
 	"github.com/snyk/vervet"
-
 	"github.com/snyk/vervet/versionware/example/resources/things"
 	"github.com/snyk/vervet/versionware/example/store"
 )

versionware/example/resources/things/2021-11-20/handlers.go

@@ -5,7 +5,6 @@ import (
 	"path"
 
 	"github.com/snyk/vervet"
-
 	"github.com/snyk/vervet/versionware/example/store"
 )