mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-09-30 17:43:12 +00:00
13ce4b7e88
* docs: add dev Postman starter collection * docs: generate complete dev Postman API collection
65 lines
3 KiB
Markdown
65 lines
3 KiB
Markdown
# SeaHaven Dev Postman collection
|
|
|
|
This directory contains the complete SeaHaven backend **dev** API collection,
|
|
generated from the live OpenAPI contract. The generated collection currently
|
|
contains every operation in the contract (368 operations across 330 paths),
|
|
including all documented parameters, request bodies, schemas, and response
|
|
codes.
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
| --- | --- |
|
|
| `SeaHaven-Dev.postman_collection.json` | Complete OpenAPI-derived Postman v2.1 collection, grouped by API tag |
|
|
| `SeaHaven-Dev.postman_environment.json` | Dev authentication environment with secret username, password, and reusable bearer token |
|
|
| `../scripts/generate-postman-collection.mjs` | Deterministic generator and coverage checker |
|
|
|
|
## Getting started
|
|
|
|
1. Import `SeaHaven-Dev.postman_collection.json` into Postman.
|
|
2. Import `SeaHaven-Dev.postman_environment.json` and select **SeaHaven - Dev**.
|
|
3. Enter the dev test account's `username` and `password` in the environment.
|
|
They are empty and secret by default; never commit or share populated values.
|
|
4. Run **Setup → Authentication - Login**. The pre-request script clears any
|
|
stale token, skips the request when either credential is missing, and never
|
|
logs credentials. A successful response stores only its non-empty `token`
|
|
field in the environment's `token` variable.
|
|
5. All generated API requests inherit collection-level `Bearer {{token}}`
|
|
authentication. They reuse the captured token automatically.
|
|
|
|
## Generated requests and examples
|
|
|
|
Every OpenAPI operation is included under its first alphabetically sorted tag.
|
|
Path, query, and header parameters retain their required/optional status,
|
|
schema hint, and description. JSON request bodies use recursively generated
|
|
illustrative placeholders from local OpenAPI schemas; multipart requests use
|
|
form-data fields and mark binary fields as files. These examples are not live
|
|
records: replace placeholder values with a valid dev fixture before sending.
|
|
No response bodies, credentials, tokens, or other dev data are stored in this
|
|
repository.
|
|
|
|
The generated test script only checks that the response status is one of the
|
|
codes documented by OpenAPI. It does not assume every operation returns `200`.
|
|
|
|
## Regenerate or check coverage
|
|
|
|
From the backend repository root:
|
|
|
|
```bash
|
|
node scripts/generate-postman-collection.mjs
|
|
node scripts/generate-postman-collection.mjs --check
|
|
```
|
|
|
|
The generator fetches `https://api.dev.seahaven.com/swagger/v1/swagger.json`,
|
|
fails on a non-JSON/non-success response, and rewrites the collection and the
|
|
empty-credential environment deterministically. `--check` compares the checked
|
|
in collection with the current contract and verifies operation count, unique
|
|
operation keys, request-body coverage, Bearer inheritance, and the explicit
|
|
no-auth login exception.
|
|
|
|
## Safety
|
|
|
|
This collection is **dev-only**. Do not point it at staging or production. Keep
|
|
`username`, `password`, and `token` local to your Postman workspace; never mark
|
|
them shared, export them, or commit them. Review every illustrative body and
|
|
parameter before running a mutating request.
|