API Spec Setup
Role: Solution Architect 🏗️
API Specs stores the Swagger/OpenAPI URL for each environment of the System. After Sync, AIPD extracts the list of endpoints and lets you link them to Features — helping the AI Agent produce technical documents with accurate endpoint information instead of placeholders.
How to use
- In System Management, select the System from the left list.
- Switch to the "API Specs" tab.
Enter a Swagger URL
The tab displays one card for each existing environment (for example: DEV, STAGING, PROD). Each card uses the color of its environment (blue for Dev, yellow for Staging, red for Prod, and so on).
Do this for each environment:
-
Enter the URL to the
swagger.jsonoropenapi.yamlfile into the card's input.- Placeholder:
Enter the full URL to the swagger.json file... - Example:
https://api.dev.yourapp.com/docs/swagger.json
- Placeholder:
-
Click the Save button (floppy-disk icon) on that card. The Save button is only active when the URL has changed from the saved value.
- Success toast: "API Spec Saved — Swagger URL for [environment name] updated successfully."
-
Click the Sync button (refresh/spinner icon) to extract the list of endpoints from Swagger.
- While syncing, the icon turns into a spinner.
- Success toast: "Swagger synced — Endpoints were extracted from the Swagger specification."
- Error toast: "Sync failed — Unable to sync endpoints from the Swagger specification."
Additional actions on each card
| Button | Action |
|---|---|
| Open Link (link icon) | Opens the Swagger URL in a new tab |
| Copy URL (copy icon) | Copies the URL to clipboard — shows "URL copied to clipboard" |
| Save (floppy icon) | Saves the URL — only active when the URL has changed |
| Sync (refresh icon) | Extracts endpoints from Swagger — only active when a URL is present |
After a successful Sync
The extracted endpoints appear in the "Associated Endpoints" dropdown when creating or editing a Feature (Features tab). Each endpoint is displayed as METHOD /path with a color based on HTTP method:
| Method | Color |
|---|---|
| GET | Blue |
| POST | Green |
| PUT | Orange |
| DELETE | Red |
| PATCH | Purple |
When Swagger is not available yet
If the team has not exposed a Swagger endpoint yet, you can:
- Skip this step and come back once the service exposes Swagger.
- Leave Feature endpoints empty — the AI can still produce documents, but they will lack concrete API information.
If the team uses NestJS, Spring Boot, or FastAPI with auto-generated Swagger, the URL usually has a fixed pattern (/api/docs, /swagger-ui, /openapi.json). Use that URL — each time you deploy a new build, click Sync so AIPD picks up the latest endpoints.
After setting up API Specs, move on to the final step 06 — System Foundation to write the foundational technical documents for the AI Agent.