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.go

@@ -17,9 +17,11 @@ import (
 
 	"github.com/pires/go-proxyproto"
 
+	"git.avsdev.uk/Go/job-search/internal/api"
 	"git.avsdev.uk/Go/job-search/internal/config"
 	"git.avsdev.uk/Go/job-search/internal/logging"
 	"git.avsdev.uk/Go/job-search/internal/middleware"
+	"git.avsdev.uk/Go/job-search/internal/store"
 	"git.avsdev.uk/Go/job-search/internal/util"
 	"git.avsdev.uk/Go/job-search/internal/websocket"
 )
@@ -61,6 +63,15 @@ func WithAccessLog(logger *log.Logger) Option {
 	}
 }
 
+// WithStore makes the server's API serve the opportunities in `store` under
+// /api/opportunities (see api.WithStore). Without it there are no
+// opportunity routes.
+func WithStore(store *store.Store) Option {
+	return func(s *Server) {
+		s.store = store
+	}
+}
+
 // WithMiddleware appends middleware to a group. This is the generic hook
 // (auth, metrics, tracing, custom header rules, ...).
 func WithMiddleware(group Group, middlewares ...Middleware) Option {
@@ -107,8 +118,12 @@ type Server struct {
 	proxyProtocolTrusted []netip.Prefix
 	csrf                 *middleware.CSRF
 	hub                  *websocket.Hub
-	started              time.Time
-	handler              http.Handler
+	// store is the opportunities' database, or nil for none.
+	store *store.Store
+	// api is the REST API mounted under /api, built from the options.
+	api     *api.API
+	started time.Time
+	handler http.Handler
 	// backgroundCtx is for background work, such as the rate limiters'
 	// janitors; backgroundCancel stops it.
 	backgroundCtx    context.Context
@@ -127,6 +142,7 @@ func New(conf *config.JSCServer, opts ...Option) (*Server, error) {
 	for _, option := range opts {
 		option(server)
 	}
+	server.api = api.New(api.WithStore(server.store))
 
 	var err error
 	server.trusted, err = util.ParseNetPrefixes(conf.Proxy.TrustedProxies)