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.

README.md

@@ -15,8 +15,9 @@ scripts/build.sh                    # build/job-search-<version>
 scripts/build.sh --release          # also package release/job-search-<version>-<arch>.tar.gz
 ```
 
-The build script runs `go generate ./...` and stamps the version from the
-latest git tag. A build from untagged commits is marked as a development build
+The build script runs `go generate ./...`, which needs `swag` installed (see
+[Installation of dev tools](#installation-of-dev-tools)), and stamps the
+version from the latest git tag. A build from untagged commits is marked as a development build
 and isn't packaged unless `--force` is also given.
 
 During development, `go run -tags sqlite_fts5 ./cmd/jobsearch` works as well.
@@ -69,6 +70,11 @@ Global flags: `--config`/`-c` (config file), `--debug`/`-d` and
 | `job-search migrate status` | Show the database version and which migrations are applied or pending |
 | `job-search version` | Print version information |
 
+`job-search serve` describes its REST API in OpenAPI 3.1 at
+`/api/openapi.json`, and shows it in Swagger UI at `/api/docs`. The
+description is generated from the handlers' annotations in `internal/api` by
+`go generate`.
+
 The `migrate` commands work on the database in `database.file`. The store
 refuses to open a database that isn't at this build's schema version, so run
 `job-search migrate` after installing a new version.
@@ -234,11 +240,15 @@ go install github.com/spf13/cobra-cli@latest
 go install git.avsdev.uk/Go/go-ocds/cmd/ocdsgen@latest
 go install github.com/pressly/goose/v3/cmd/goose@latest
 go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc6
 ```
 
 `goose` creates new migration files (see `internal/store`); the migrations
 themselves are applied by `job-search migrate`. `golangci-lint` uses the
-project's `.golangci.json`.
+project's `.golangci.json`. `swag` generates the API's OpenAPI 3.1 spec from
+the handlers' comments (`swag init --v3.1`). Its v2, the version with OpenAPI
+3 support, has only had release candidates so far, so it is pinned to one
+rather than `@latest`.
 
 Ensure that the GOBIN path ($HOME/go/bin) is added to the environment before
 running any of the tools.