Professional OpenAPI 3.1.0 specification for CocoaFlow, a cocoa industry management platform. The repository provides the API contract, interactive documentation, and generated artifacts (TypeScript client and Postman collection) with CI/CD and containerized deployment.
CocoaFlow API defines a production-ready contract for cocoa industry operations: farmer and farm management, GPS and inspection data, Rainforest Alliance certification, campaigns, markets, transactions, training, and subscriptions. The spec is the single source of truth for frontend and backend integration.
- OpenAPI 3.1.0 with modular paths and reusable components
- 50+ endpoints across auth, users, companies, farms, projects, campaigns, markets, transactions, training, inspections, audits, and subscriptions
- Standardized request/response examples and error schemas (4xx/5xx)
- JWT Bearer and API key security; rate limiting and validation
- Generated TypeScript client (OpenAPI Generator) and Postman collection for testing
- CI/CD (GitHub Actions), Docker image for docs, and deployment to GitHub Pages / Vercel
- Node.js 22+
- npm 8+
- Docker (optional)
git clone git@github.com:frckbrice/project-api_spec.git
cd project-api_spec
npm install
npm run docs:serveDocumentation is served at http://localhost:8080.
| Command | Description |
|---|---|
npm run docs:serve |
Serve interactive docs (port 8080) |
npm run docs:build |
Build static documentation |
npm run bundle |
Bundle spec to dist/cocoaflow-api.yaml |
npm run lint |
Lint OpenAPI spec |
npm run validate |
Validate against OpenAPI 3.1.0 |
npm run test |
Lint, validate, format check |
npm run generate:client |
Generate TypeScript client to generated/typescript/ |
npm run generate:postman |
Generate Postman collection to generated/postman/ |
docker build -t cocoaflow-api-docs .
docker run -p 8080:8080 cocoaflow-api-docs| Environment | URL | Notes |
|---|---|---|
| GitHub Pages | project-api_spec | Published docs |
| Raw spec | cocoaflow-api.yaml | Bundled OpenAPI YAML |
| Local | http://localhost:8080 |
After npm run docs:serve |
project-api_spec/
├── swt_api_spec/ # OpenAPI source
│ ├── components/
│ │ ├── schemas/ # Data models
│ │ ├── responses/ # Reusable response definitions
│ │ └── parameters/ # Shared parameters
│ ├── paths/ # Endpoints by domain (auth, user, companies, farm, project, etc.)
│ └── cocoaflow-api.yaml # Root spec
├── dist/ # Bundled spec (output of bundle)
├── generated/ # Generated artifacts (gitignored; run generate scripts to create)
│ ├── typescript/ # Generated TypeScript client (npm run generate:client)
│ └── postman/ # Generated Postman collection (npm run generate:postman)
├── postman/ # Legacy/unused; Postman output lives in generated/postman/
├── public/ # Built documentation assets
├── .github/workflows/ # CI/CD
├── redocly.yaml # Redocly and lint config
├── Dockerfile # Docs server image
└── package.json
- Add or edit YAML under
swt_api_spec/paths/(andcomponents/schemas/if needed). - Reference new paths in
swt_api_spec/cocoaflow-api.yamlunderpaths:. - Include request body examples for POST/PUT/PATCH and response examples for success and errors.
- Run
npm run lint && npm run validate, thennpm run docs:serveto verify.
- Auth: JWT Bearer (primary), API key for service-to-service, OAuth2 optional.
- Practices: HTTPS, rate limiting, input validation, CORS, security headers.
- Compliance: Rainforest Alliance-related flows, audit considerations, data privacy.
- TypeScript client:
npm run generate:client(requiresnpm run bundlefirst). Output ingenerated/typescript/. - Postman collection:
npm run generate:postman. Output ingenerated/postman/. - Interactive API Documentation: https://project-apispec.vercel.app
- Raw OpenAPI Specification: https://project-apispec.vercel.app/cocoaflow-api.yaml
- GitHub Repository: https://github.com/frckbrice/project-api_spec
- Issue Tracking: https://github.com/frckbrice/project-api_spec/issues
Apache License 2.0. See LICENSE.
OpenAPI 3.1.0, Redocly, Docker, GitHub Actions, TypeScript.