61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
---
|
|
description: The definitive workflow for safely updating API specifications and generating Postman tests to ensure 100% consistency and prevent data loss.
|
|
---
|
|
|
|
# Workflow: API Spec & Test Generation
|
|
|
|
This workflow establishes `openapi.yaml` as the single source of truth for all API development. The Postman collection is **always generated** from this file. **NEVER edit the Postman JSON file directly.** This prevents inconsistencies and the kind of file corruption we have experienced.
|
|
|
|
## Guiding Principles
|
|
|
|
- **OpenAPI is the ONLY Source of Truth:** All API changes begin and end with `docs/api/openapi.yaml`.
|
|
- **Postman is a GENERATED ARTIFACT:** The collection file is treated as build output. It is never edited by hand.
|
|
- **Validate Before Generating:** Always validate the OpenAPI spec _before_ attempting to generate the Postman collection.
|
|
|
|
## Steps
|
|
|
|
### 1. Update the OpenAPI Specification (`docs/api/openapi.yaml`)
|
|
|
|
- **Identify API Changes:** Review the Groovy source code (e.g., `src/com/umig/api/v2/*.groovy`) to identify any new, modified, or removed endpoints.
|
|
- **Edit the Spec:** Carefully add, modify, or remove the corresponding endpoint definitions under `paths` and schemas under `components/schemas`.
|
|
- **Best Practice:** Use `allOf` to extend existing schemas non-destructively (e.g., adding audit fields to a base `User` schema).
|
|
- **Use an IDE with OpenAPI support** to get real-time linting and validation.
|
|
|
|
### 2. Validate the OpenAPI Specification
|
|
|
|
- **CRITICAL:** Before proceeding, validate your `openapi.yaml` file.
|
|
- Use your IDE's built-in OpenAPI preview or a dedicated linter.
|
|
- **DO NOT proceed if the file has errors.** Fix them first. This is the most important step to prevent downstream issues.
|
|
|
|
### 3. Generate the Postman Collection
|
|
|
|
- **Navigate to the correct directory** in your terminal. The command must be run from here:
|
|
```bash
|
|
cd docs/api/postman
|
|
```
|
|
- **Run the generation command:**
|
|
```bash
|
|
// turbo
|
|
npx openapi-to-postmanv2 -s ../openapi.yaml -o ./UMIG_API_V2_Collection.postman_collection.json -p -O folderStrategy=Tags
|
|
```
|
|
- **Note on `npx`:** The `npx` command runs the `openapi-to-postmanv2` package without requiring a global installation. If you see `command not found`, ensure you are using `npx`.
|
|
|
|
### 4. Verify the Changes
|
|
|
|
- **Review the Diff:** Use `git diff` to review the changes to `UMIG_API_V2_Collection.postman_collection.json`. Confirm that the new endpoint has been added and that no unexpected changes have occurred.
|
|
- **Test in Postman:** (Optional but recommended) Import the newly generated collection into Postman and run a few requests against a local dev environment to ensure correctness.
|
|
|
|
### 5. Document and Commit
|
|
|
|
- **Commit all changes:** Add the modified `openapi.yaml` and the generated `UMIG_API_V2_Collection.postman_collection.json` to your commit.
|
|
- **Update Changelog:** Add an entry to `CHANGELOG.md` detailing the API changes.
|
|
- **Update Dev Journal:** Create a developer journal entry summarizing the work done.scribe any removals or replacements and the rationale.
|
|
|
|
---
|
|
|
|
**Key Principles:**
|
|
|
|
- Never erase or overwrite existing tests/specs unless required by an API change.
|
|
- Every endpoint in the API must be present and tested in both Postman and OpenAPI.
|
|
- Consistency, completeness, and traceability are paramount.
|