feat(api): add OpenAPI spec, workflow doc, and GH Actions trigger#178
feat(api): add OpenAPI spec, workflow doc, and GH Actions trigger#178
Conversation
- api-server/openapi-spec.ts: OpenAPI 3.0 spec for the job-based API
server (/health, /jobs, /jobs/{id}) with full request/response schemas,
auth schemes, and error codes
- WORKFLOW.md: end-to-end architecture doc covering Notion → API Server
→ GitHub → Pages flow and the principle that Slack notifications come
from GH workflows, never the API server directly
- .github/workflows/api-notion-fetch.yml: workflow_dispatch + repository_
dispatch trigger that calls the API server to run Notion jobs (fetch,
translate, status, publish)
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
🐳 Docker Image PublishedYour Docker image has been built and pushed for this PR. Image Reference: Platforms: linux/amd64, linux/arm64 TestingTo test this image: docker pull docker.io/communityfirst/comapeo-docs-api:pr-178
docker run -p 3001:3001 docker.io/communityfirst/comapeo-docs-api:pr-178Built with commit 20dbcd5 |
🚀 Preview DeploymentYour documentation preview is ready! Preview URL: https://pr-178.comapeo-docs.pages.dev 🔄 Content: Regenerated 5 pages from Notion (content branch was empty, used fallback)
This preview will update automatically when you push new commits to this PR. Built with commit 20dbcd5 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 20dbcd5a9d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| default: "notion:fetch-all" | ||
| type: choice | ||
| options: | ||
| - notion:fetch-all | ||
| - notion:fetch |
There was a problem hiding this comment.
The workflow defaults to notion:fetch-all and exposes notion:fetch, but POST /jobs only accepts job types from VALID_JOB_TYPES (derived from api-server/job-executor.ts), where fetch types are fetch-all/fetch-ready (api-server/validation-schemas.ts). With the current default, scheduled runs and default manual dispatches send an invalid type and the API rejects the request with 400, so fetch jobs cannot be started from this workflow.
Useful? React with 👍 / 👎.
| -d "$BODY") | ||
|
|
||
| # Parse response | ||
| JOB_ID=$(echo "$RESPONSE" | jq -r '.data.jobId // empty') |
There was a problem hiding this comment.
JOB_ID is extracted from .data.jobId, but handleCreateJob returns a top-level payload ({ jobId, status }) in api-server/routes/jobs.ts, so this expression resolves empty and the step fails even when job creation succeeded. The same .data.* assumption is repeated in polling (.data.status, .data.result.*), which would also misread job state for fetch jobs; this workflow should read top-level keys for these endpoints.
Useful? React with 👍 / 👎.
| apiKeyAuth: { | ||
| type: "http", | ||
| scheme: "api-key", | ||
| description: "Api-Key header authentication using API key", |
There was a problem hiding this comment.
apiKeyAuth is defined as type: "http" with scheme: "api-key", which is not a valid OpenAPI security scheme value and can break strict spec validators/client generation. For header-based API keys, OpenAPI expects type: "apiKey" plus in: "header" and name so consumers can authenticate correctly.
Useful? React with 👍 / 👎.
1 participant
Summary
api-server/openapi-spec.ts— complete OpenAPI 3.0 spec for the job-based API server (/health,/jobs,/jobs/{id}endpoints with auth, error codes, request/response schemas)WORKFLOW.md— architecture doc describing the Notion → API Server → GitHub Actions → Pages pipeline; establishes that the API server never sends Slack notifications (GH workflows do).github/workflows/api-notion-fetch.yml— manualworkflow_dispatch+repository_dispatchtrigger allowing API server jobs to be fired from GH Actions (notion:fetch-all, notion:fetch, notion:translate, notion:count-pages, status commands)These files were developed alongside the translation pipeline work in PR #169 but kept separate to avoid mixing concerns.
Test plan
WORKFLOW.mdaccurately reflects current pipeline architecture