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/cli/serve/command.go

@@ -34,7 +34,8 @@ It also runs a worker for every enabled source, as fetcher service does,
 saving what they fetch to database.file if it is set, and pushing an
 OpportunitiesUpdated event to every WebSocket client when a save stores new
 opportunities or new releases. A source that stops with an error stops the
-server too, and the server stopping stops the sources.`,
+server too, and the server stopping stops the sources. With database.file
+set, the API serves the stored opportunities under /api/opportunities.`,
 		PersistentPreRun: func(cmd *cobra.Command, args []string) {
 			slog.Debug("command persistent pre-run", "command", "serve")
 		},
@@ -112,21 +113,15 @@ server too, and the server stopping stops the sources.`,
 				stop()
 			}()
 
-			appServer, err := server.New(&conf.Server, options...)
-			if err != nil {
-				return err
-			}
-
-			// runCtx stops whichever of the server and the sources is still
-			// running once the other has stopped.
-			runCtx, cancelRun := context.WithCancel(ctx)
-			defer cancelRun()
-
+			// The store is shared by the sources, which save to it, and the API,
+			// which serves it.
 			var fetcherOptions []fetcher.Option
 			opportunityStore, openErr := cli.OpenConfiguredStore(ctx, conf)
 			switch {
 			case errors.Is(openErr, cli.ErrNoDatabase):
-				slog.Warn("not storing fetched opportunities", "reason", openErr)
+				slog.Warn(
+					"opportunities aren't stored or served", "reason", openErr,
+				)
 			case openErr != nil:
 				return openErr
 			default:
@@ -136,8 +131,21 @@ server too, and the server stopping stops the sources.`,
 				fetcherOptions = append(
 					fetcherOptions, fetcher.WithStore(opportunityStore),
 				)
+				options = append(
+					options, server.WithStore(opportunityStore),
+				)
 			}
 
+			appServer, err := server.New(&conf.Server, options...)
+			if err != nil {
+				return err
+			}
+
+			// runCtx stops whichever of the server and the sources is still
+			// running once the other has stopped.
+			runCtx, cancelRun := context.WithCancel(ctx)
+			defer cancelRun()
+
 			// Events from the sources, such as new opportunities, are pushed to
 			// every WebSocket client.
 			var bus events.Bus