bwilliams
70d62f280e
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.
25 lines
1.0 KiB
Go
25 lines
1.0 KiB
Go
// Package api implements the REST API mounted under /api. New assembles it
|
|
// (api.go): the opportunities, read-only apart from their marks
|
|
// (opportunities.go), and the API's own OpenAPI 3.1 description and docs
|
|
// viewer (openapi.go). New resources are added in New and Routes, so the
|
|
// server only mounts the API.
|
|
//
|
|
// The description is generated from the swag annotations on this package's
|
|
// handlers by go generate (swag v2, see the README's dev tools), into
|
|
// openapi/swagger.json. The annotations below are the API's general
|
|
// information.
|
|
//
|
|
// @title JobSearch API
|
|
// @version 1.0
|
|
// @description Procurement opportunities fetched by JobSearch, and the user's
|
|
// @description marks on them. Errors are RFC 9457 problem details.
|
|
// @servers.url /api
|
|
//
|
|
// @securityDefinitions.apikey CSRF
|
|
// @in header
|
|
// @name X-CSRF-Token
|
|
// @description From GET /api/csrf; send its cookie too.
|
|
package api
|
|
|
|
//go:generate swag init --v3.1 --generalInfo doc.go --dir . --parseInternal --parseDependencyLevel 1 --outputTypes json --output openapi
|