feat(API): improve GET /projects/{project_id}/screenshots documentation#1161
Closed
Stephen Lumenta (sbl) wants to merge 3 commits into
Closed
feat(API): improve GET /projects/{project_id}/screenshots documentation#1161Stephen Lumenta (sbl) wants to merge 3 commits into
Stephen Lumenta (sbl) wants to merge 3 commits into
Conversation
…ntation Fix rubric dimensions: conceptual_clarity, error_documentation, example_quality, frontmatter_metadata, reference_completeness, schema_completeness, self_contained_examples, stable_identifiers, vocabulary_consistency. - operationId corrected to screenshots/show (was screenshot/show) - branch parameter uses shared $ref instead of inline duplicate - description expanded with what/why/access-control/branch semantics - 403 response lists all three distinct paths to forbidden - response example added with realistic values derived from serializer - curl example uses full URL with realistic project_id + screenshot id - schema properties gain descriptions and per-field examples Part of DEVEX-60. Source-grounded via Phrase-Engineering/strings-app.
Addresses rubric gaps for the screenshots list endpoint: - conceptual_clarity: expand description with ordering behaviour, Link header pagination, Attachable Screenshots feature requirement, and branch scoping semantics — derived from ScreenshotRepository and the restrict_feature! before-action in ScreenshotsController - error_documentation: add descriptive overrides for 403 (scope + feature gate) and 404 (project / branch / key_id not found); the key_id 404 path is verified via find_by! in ScreenshotRepository#23 - example_quality: replace :project_id placeholder with a realistic 32-char hex code; add a second curl sample showing key_id + pagination - frontmatter_metadata: richer description covering the use-case and constraints - reference_completeness: replace inline branch param block with $ref: ../../parameters.yaml#/branch - schema_completeness: confirmed existing screenshot.yaml already carries per-field descriptions and format annotations (no change needed) - self_contained_examples: both curl samples use full https://api.phrase.com URL and include -u USERNAME_OR_ACCESS_TOKEN; add inline 200 response example array showing two realistic screenshot objects - stable_identifiers: operationId screenshots/list unchanged (already correct) - vocabulary_consistency: update key_id description from vague "filter by key" to "Filter results to screenshots that contain a marker for the given translation key ID" Part of DEVEX-60 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Stephen Lumenta (sbl)
deleted the
en-api-strings-screenshots-list-screenshots
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes rubric dimensions: conceptual_clarity, error_documentation, example_quality, frontmatter_metadata, reference_completeness, schema_completeness, self_contained_examples, stable_identifiers, vocabulary_consistency
Part of DEVEX-60
Source-grounded via Phrase-Engineering/strings-app.
Changes
conceptual_clarity: Expanded description with ordering behaviour (no-marker screenshots first, then by created_at desc), Link-header pagination, Attachable Screenshots feature requirement, and branch scoping semantics — all derived from
ScreenshotRepositoryandrestrict_feature!inScreenshotsController.error_documentation: Added descriptive overrides for 403 (scope + feature gate) and 404 (project / branch / key_id not found). The key_id 404 path is verified via
find_by!inScreenshotRepository#22.example_quality: Replaced
:project_idcolon-placeholder with a realistic 32-char hex project ID. Added a second curl sample showingkey_id+ pagination parameters.reference_completeness: Replaced inline
branchparameter block with$ref: ../../parameters.yaml#/branch.self_contained_examples: Both curl samples use the full
https://api.phrase.com/v2/...URL and include-u USERNAME_OR_ACCESS_TOKEN. Added an inline 200 response example array with two realistic screenshot objects.vocabulary_consistency: Updated key_id parameter description from vague "filter by key" to "Filter results to screenshots that contain a marker for the given translation key ID" — consistent with the
key_idparameter name.schema_completeness: Existing
schemas/screenshot.yamlalready carries per-field descriptions, examples, and date-time format annotations — no change needed there.stable_identifiers:
operationId: screenshots/listis correct per conventions — unchanged.