Skip to content

fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation#1190

Open
Stephen Lumenta (sbl) wants to merge 3 commits into
mainfrom
devex-115-screenshots-update-a-screenshot
Open

fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation#1190
Stephen Lumenta (sbl) wants to merge 3 commits into
mainfrom
devex-115-screenshots-update-a-screenshot

Conversation

@sbl

Copy link
Copy Markdown
Contributor

Improves the documentation for patch /projects/{project_id}/screenshots/{id}: sharper descriptions, parameter docs, error responses, and usage examples.

Drafted with AI assistance and grounded in the API implementation. Please review for technical accuracy before merging; nothing is merged automatically.

🤖 Generated with Claude Code

@sbl Stephen Lumenta (sbl) added the developer-hub-api-quality API doc quality fix from the API Grader label Jun 15, 2026
@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

12 changes: 1 error, 0 warning, 11 info
error	[request-body-media-type-removed] at doc/compiled.json
	in API PATCH /projects/{project_id}/screenshots/{id}
		removed the media type `application/json` from the request body

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/api_name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_encoding` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_file` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/description` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/exportable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/extension` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/importable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/includes_locale_information` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/renders_default_locale` became required for the status `200`

info	[request-body-media-type-added] at doc/compiled.json
	in API PATCH /projects/{project_id}/screenshots/{id}
		added the media type `multipart/form-data` to the request body

@sbl Stephen Lumenta (sbl) changed the title feat(API): improve patch /projects/{project_id}/screenshots/{id} documentation fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation Jun 17, 2026
Stephen Lumenta (sbl) and others added 2 commits June 17, 2026 21:12
Apply the batch review conventions:
- Move the per-status 'Errors:' prose and the scope/permission sentence
  out of the top-level description and onto the response objects.
- Remove the non-standard 'response:' block from each code sample; samples
  now show only the request, and the 200 example documents the response.
- CLI sample: use <project_id>/<id>/<token> placeholders instead of
  concrete slug-like values.
- Normalize the branch property to 'specify the branch to use'.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
An empty 'required' array is invalid under the OpenAPI 3.0 meta-schema
(it must have at least one entry), which was failing 'swagger-cli
validate' in the lint gate. The endpoint has no required fields, so the
key is simply removed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

developer-hub-api-quality API doc quality fix from the API Grader

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant