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.
55 lines
1.6 KiB
Go
55 lines
1.6 KiB
Go
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
|
|
}
|