fix: restructure artifacts directory for $ref consumption#2
fix: restructure artifacts directory for $ref consumption#2
Conversation
…roject#598) With the introduction of release automation, the x-camara-commonalities field is set automatically and can now use the full version string from VERSION.yaml instead of just the minor version. Updated the API Design Guide and artifacts accordingly.
Comment out {{SPECIFIC_CODE}} and {{field}} placeholder patterns in
Generic error responses (400, 403, 404, 409, 422). Commented lines
remain as documentation for API developers. The file becomes directly
consumable via $ref by bundling tools, Spectral, and YAML parsers.
Fixes camaraproject#601
Re-indent 5 commented-out placeholder blocks to match the indentation of the preceding content line, avoiding false positives from yamllint's buggy comments-indentation rule.
…ect#603) Phase 1 of artifacts restructuring: - Move CAMARA_common.yaml to artifacts/common/ directory - Add api-templates/sample-service.yaml demonstrating $ref consumption - Update documentation references to new path The sample-service template demonstrates two patterns for error responses: - Option A: pure $ref for responses using only generic error codes - Option B: local response definition extending generic errors with API-specific codes (ResourceNotFound404 example) Next steps (after camaraproject#604 merges): - Add CAMARA_event_common.yaml with CloudEvent/Source/DateTime schemas - Add notification-templates/sample-notification.yaml - Add event-related API templates (implicit events, subscriptions) - Migrate camara-cloudevents/ content to new structure
|
|
I recommend to do that in a separate PR. To avoid to keep the directory, I would put the information into the README on artifacts/ level. That might break some personal environments who have checked out the Commonalities repo and using the linting rules locally directly from there ... but it is indeed better to have the rules only in one place. I'm waiting for the merge of camaraproject#602 to rebase and then create the PR in Commonalities upstream. |
|
Closing as there is now camaraproject#606 |
2 participants
What type of PR is this?
What this PR does / why we need it:
Phase 1 of artifacts directory restructuring (camaraproject/Commonalities#603).
Establishes the
common/andapi-templates/directory structure so that$refpaths in templates are identical to those in API repositories:CAMARA_common.yamltoartifacts/common/CAMARA_common.yamlartifacts/api-templates/sample-service.yaml— a request-response CRUD template demonstrating$refconsumption of common schemas, error responses, parameters, headers, and security schemesREADME.mdandCAMARA-API-Design-Guide.mdThe sample-service template demonstrates two patterns for error responses:
$ref): For responses using only generic error codes — e.g.,$ref: "../common/CAMARA_common.yaml#/components/responses/Generic404"ResourceNotFound404withIDENTIFIER_NOT_FOUNDalongside genericNOT_FOUNDPrerequisites cherry-picked (will be dropped on rebase after upstream merge):
$refconsumptionWhich issue(s) this PR fixes:
Fixes camaraproject#603 (phase 1)
Does this PR introduce a breaking change?
Special notes for reviewers:
This is a draft PR for early discussion. It will be retargeted to
camaraproject/Commonalitiesafter camaraproject#599 and camaraproject#602 merge upstream.Next steps (phase 2, after #604 merges):
common/CAMARA_event_common.yamlwith CloudEvent/Source/DateTime schemas (OWASP-aligned)notification-templates/sample-notification.yamlreplacingnotification-as-cloud-event.yamlsample-implicit-events.yaml,sample-service-subscriptions.yaml)camara-cloudevents/content to new structureValidation results (0 errors):
Redocly bundle resolves all
$refsuccessfully:Spectral lint on bundled output (1 pre-existing warning from CAMARA_common.yaml openId):
Spectral also resolves cross-file
$refdirectly on source files — same result.Redocly OpenAPI validation:
Changelog input
Additional documentation