Added the opportunities REST API, read-only apart from their marks, described in OpenAPI 3.1 with swag

GET /api/opportunities lists the stored opportunities, newest release first,
a page at a time (offset, and limit up to 100, default 50); has_more says
whether another page follows. GET /api/opportunities/{uuid} returns one with
its releases. PUT and DELETE /api/opportunities/{uuid}/marks/{mark} set and
clear one mark (hidden, skipped, interested, bid_submitted, won, lost) and
return them all; won and lost exclude each other (409). The API uses the
types in internal/types, and changing a mark is made atomic, as the store
replaces all of an opportunity's marks at once. The marks are found by
reflection: every bool field of types.OpportunityMarks, by its JSON name, so
a new mark needs no API change.

The API has one entry point, api.New, with its dependencies as options
(api.WithStore), and the server only mounts it under /api, keeping the
middleware. New resources are added inside internal/api. job-search serve
passes server.WithStore when database.file is set, opening the store before
the server; without one there are no opportunity routes.

The API is described by swag v2 annotations on the handlers. go generate
writes the OpenAPI 3.1 description (git-ignored, like the OCDS types), which
the server embeds and serves at /api/openapi.json, with Swagger UI at
/api/docs. A test checks the description and the routes match. swag is in
the README's dev tools, pinned to v2.0.0-rc6, and the build now needs it.

internal/api/openapi_test.go

@@ -0,0 +1,136 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.avsdev.uk/Go/job-search/internal/store"
+)
+
+// The description is served as JSON, and the docs page points at it.
+func TestDocsRoutes(t *testing.T) {
+	router := chi.NewRouter()
+	New().Routes(router)
+	server := httptest.NewServer(router)
+	t.Cleanup(server.Close)
+
+	res, err := http.Get(server.URL + "/openapi.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	var spec struct {
+		OpenAPI string `json:"openapi"`
+	}
+	if err := json.NewDecoder(res.Body).Decode(&spec); err != nil {
+		t.Fatal(err)
+	}
+	if res.Header.Get("Content-Type") != "application/json" ||
+		spec.OpenAPI != "3.1.0" {
+		t.Errorf(
+			"openapi.json: %s, openapi %q; want JSON, 3.1.0",
+			res.Header.Get("Content-Type"), spec.OpenAPI,
+		)
+	}
+
+	res, err = http.Get(server.URL + "/docs")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	page, _ := io.ReadAll(res.Body)
+	if !strings.Contains(string(page), `url: "openapi.json"`) {
+		t.Errorf("docs page doesn't load openapi.json:\n%s", page)
+	}
+}
+
+// Every route the API serves, apart from its description's own, is in the
+// description, and the description has no route that isn't served, so the
+// annotations can't fall behind as resources are added.
+func TestOpenAPICoversRoutes(t *testing.T) {
+	var spec struct {
+		Paths map[string]map[string]json.RawMessage `json:"paths"`
+	}
+	if err := json.Unmarshal(openAPISpec, &spec); err != nil {
+		t.Fatal(err)
+	}
+	documented := map[string]bool{}
+	for path, operations := range spec.Paths {
+		for method := range operations {
+			documented[strings.ToUpper(method)+" "+path] = true
+		}
+	}
+
+	// A store that is never opened: registering routes doesn't use it.
+	router := chi.NewRouter()
+	New(WithStore(&store.Store{})).Routes(router)
+	description := map[string]bool{
+		"GET /openapi.json": true,
+		"GET /docs":         true,
+	}
+	served := map[string]bool{}
+	err := chi.Walk(router, func(
+		method, route string, _ http.Handler, _ ...func(http.Handler) http.Handler,
+	) error {
+		if !description[method+" "+route] {
+			served[method+" "+route] = true
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for route := range served {
+		if !documented[route] {
+			t.Errorf("%s is served but not in the OpenAPI description", route)
+		}
+	}
+	for route := range documented {
+		if !served[route] {
+			t.Errorf("%s is in the OpenAPI description but not served", route)
+		}
+	}
+}
+
+// The description's list of marks matches OpportunityMarks, so its Enums
+// annotation can't fall behind the struct.
+func TestOpenAPIMarkEnum(t *testing.T) {
+	var spec struct {
+		Paths map[string]map[string]struct {
+			Parameters []struct {
+				Name   string `json:"name"`
+				Schema struct {
+					Enum []string `json:"enum"`
+				} `json:"schema"`
+			} `json:"parameters"`
+		} `json:"paths"`
+	}
+	if err := json.Unmarshal(openAPISpec, &spec); err != nil {
+		t.Fatal(err)
+	}
+
+	want := strings.Join(markNames, ",")
+	checked := 0
+	operations := spec.Paths["/opportunities/{uuid}/marks/{mark}"]
+	for method, operation := range operations {
+		for _, parameter := range operation.Parameters {
+			if parameter.Name != "mark" {
+				continue
+			}
+			checked++
+			if got := strings.Join(parameter.Schema.Enum, ","); got != want {
+				t.Errorf("%s mark enum = %s; want %s", method, got, want)
+			}
+		}
+	}
+	if checked != 2 {
+		t.Errorf("checked the mark of %d routes; want 2 (PUT, DELETE)", checked)
+	}
+}