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

@@ -0,0 +1,54 @@
+package api
+
+import (
+	_ "embed"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// openAPISpec is the API's OpenAPI 3.1 description, generated by go generate
+// (see doc.go).
+//
+//go:embed openapi/swagger.json
+var openAPISpec []byte
+
+// docsPage shows openapi.json, relative to /api/docs, in Swagger UI, loaded
+// from jsDelivr at a fixed version. A content security policy
+// (server.headers.content_security_policy) must allow that.
+const docsPage = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>JobSearch API</title>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui.css">
+</head>
+<body>
+<div id="ui"></div>
+<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui-bundle.js"></script>
+<script>
+SwaggerUIBundle({url: "openapi.json", dom_id: "#ui"});
+</script>
+</body>
+</html>
+`
+
+// docsRoutes registers the API's description on router: GET /openapi.json,
+// the OpenAPI 3.1 description, and GET /docs, a viewer of it.
+func docsRoutes(router chi.Router) {
+	router.Get("/openapi.json", serveOpenAPISpec)
+	router.Get("/docs", serveDocsPage)
+}
+
+// serveOpenAPISpec serves GET /openapi.json.
+func serveOpenAPISpec(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.Write(openAPISpec) //nolint:errcheck,gosec // the client may have gone
+}
+
+// serveDocsPage serves GET /docs.
+func serveDocsPage(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Write([]byte(docsPage)) //nolint:errcheck,gosec // the client may have gone
+}