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/server/server_test.go

@@ -9,6 +9,7 @@ import (
 	"net/http"
 	"net/http/cookiejar"
 	"net/http/httptest"
+	"path/filepath"
 	"strings"
 	"sync"
 	"testing"
@@ -20,6 +21,8 @@ import (
 
 	"git.avsdev.uk/Go/job-search/internal/config"
 	"git.avsdev.uk/Go/job-search/internal/middleware"
+	"git.avsdev.uk/Go/job-search/internal/store"
+	"git.avsdev.uk/Go/job-search/internal/types"
 	ws "git.avsdev.uk/Go/job-search/internal/websocket"
 )
 
@@ -87,6 +90,31 @@ func clientWithJar(t *testing.T) *http.Client {
 	}
 }
 
+// apiClient returns a function making requests to the test server ts with
+// client c, sending body as JSON and, if withToken, the CSRF token tok.
+func apiClient(
+	t *testing.T, ts *httptest.Server, c *http.Client, tok csrfToken,
+) func(method, path, body string, withToken bool) *http.Response {
+	t.Helper()
+	return func(method, path, body string, withToken bool) *http.Response {
+		req, _ := http.NewRequest(method, ts.URL+path, strings.NewReader(body))
+		if body != "" {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		if withToken {
+			req.Header.Set(tok.Header, tok.Token)
+		}
+		res, err := c.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		t.Cleanup(func() {
+			res.Body.Close()
+		})
+		return res
+	}
+}
+
 // Unsafe API requests need the CSRF token: without it they are rejected
 // before routing; with it they reach the router (here, 405 from a GET-only
 // route).
@@ -307,3 +335,61 @@ func (b *syncBuffer) String() string {
 	defer b.mu.Unlock()
 	return b.buffer.String()
 }
+
+// With WithOpportunityStore the opportunities are served, and changing a mark
+// needs the CSRF token; without it there are no opportunity routes.
+func TestOpportunityRoutes(t *testing.T) {
+	opportunityStore, err := store.Open(
+		context.Background(),
+		filepath.Join(t.TempDir(), "server.db"),
+		store.WithAutoMigrate(),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		opportunityStore.Close()
+	})
+	_, err = opportunityStore.SaveOpportunity(
+		context.Background(),
+		&types.Opportunity{
+			UUID:     "ocds-1",
+			UUIDType: "ocid",
+			Releases: []types.OpportunityRelease{
+				{
+					ReleaseID:   "r1",
+					ReleaseDate: time.Now(),
+					JSON:        "{}",
+				},
+			},
+		},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ts := newTestServer(t, nil, WithStore(opportunityStore))
+	c := clientWithJar(t)
+	do := apiClient(t, ts, c, getToken(t, c, ts.URL))
+
+	if res := do("GET", "/api/opportunities", "", false); res.StatusCode != 200 {
+		t.Errorf("list: %d; want 200", res.StatusCode)
+	}
+	mark := "/api/opportunities/ocds-1/marks/interested"
+	if res := do("PUT", mark, "", false); res.StatusCode != http.StatusForbidden {
+		t.Errorf("mark without token: %d; want 403", res.StatusCode)
+	}
+	if res := do("PUT", mark, "", true); res.StatusCode != 200 {
+		t.Errorf("mark with token: %d; want 200", res.StatusCode)
+	}
+
+	without := newTestServer(t, nil)
+	res, err := http.Get(without.URL + "/api/opportunities")
+	if err != nil {
+		t.Fatal(err)
+	}
+	res.Body.Close()
+	if res.StatusCode != http.StatusNotFound {
+		t.Errorf("no store: %d; want 404", res.StatusCode)
+	}
+}