This package contains OpenAPI definitions for Ampersand's API endpoints and schemas.
Ensure you have pnpm installed globally
npm install -g pnpmInstall dependencies
pnpm i- Create a new pull request
- Run
make lintto ensure that the linter passes - Request review, and merge the PR once it is approved. Please note that if the full spec has already been approved in a doc, or if you are simply updating descriptions or examples, you do not neeed to request PR review.
- After a few minutes, a Github Action on the docs repo will auto-update the online API reference.
The json spec files are auto generated on a commit (setup as a pre-commit hook) but if you'd like to generate it manually run the following
pnpm run gen:json- Naming: Use descriptive operation and type names, as generated SDKs & docs may reuse these names.
- Tags: The tags determine which section in the reference docs the endpoint will be grouped under, therefore you should always include tags for new endpoints.
- Required Request Parameters: Ensure you mark parameters (query or path) and request bodies as
required: truewhen needed. - Avoid Duplicates: Do not create duplicate paths or types across specs unless absolutely necessary. Duplicate definitions (based on URL and method) can cause issues when generating unified docs or SDKs.
- Using oneOf: Apply
oneOfonly to entire schemas, not individual properties. While the linter might not flag it, using it on properties can lead to errors in SDK generation. - Documentation: Provide clear descriptions and examples for each operation, as these details will show up in our docs.
- Error Handling: Include distinct responses only when the response types differ. Otherwise, use a
defaultresponse to group similar responses. For instance, if an operation returns the same schema structure for both 404 and 502 (with different messages) but a completely different structure for 200, define two response schemas: one for 200 and one default.