fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation by sbl · Pull Request #1190 · phrase/strings-openapi

Stephen Lumenta (sbl) · 2026-06-15T14:59:30Z

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

…mentation

github-actions · 2026-06-15T15:00:18Z

API changelog (oasdiff)

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

5 changes: 1 error, 0 warning, 4 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	[new-optional-request-property] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links
		added the new optional request property `strategy`

info	[request-body-became-optional] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links
		request body became optional

info	[response-media-type-added] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links
		added the media type `application/json` for the response with 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

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>

Review feedback: error response descriptions should stay in the shared responses.yaml for consistency, not be re-authored inline per operation. Under OpenAPI 3.0 a description sibling of $ref is ignored anyway, so the inline text never rendered. Strip the inline $ref-sibling response descriptions (now bare $refs); the shared response owns the wording. Genuinely custom (non-$ref) response bodies are left intact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Strings convention: never hand-author Curl or CLI v2 samples. Mintlify renders the request sample (curl + the multi-language playground) and the response from the OpenAPI operation itself, so a hand-written x-code-samples block drifts and overrides the correct auto-generated one; a CLI v2 sample is not spec-derivable at all. Remove the block so Mintlify renders. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Stephen Lumenta (sbl) · 2026-06-24T13:24:13Z

API surface change — reviewer note

This PR changes the request-body media type of PATCH /projects/{project_id}/screenshots/{id} from application/json to multipart/form-data, which is correct for an endpoint that accepts a binary filename upload (and matches POST .../screenshots). oasdiff flags request-body-media-type-removed. No change to live API behavior; it corrects the documented transport.

Applying breaking-change-approved to clear the gate.

The 200 response already references `schemas/screenshot.yaml#/screenshot`, which carries a schema-level example covering every field. The inline example here just duplicated it (and drifts from the canonical one the show endpoint renders). Remove it so update and show render the same shared example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Regenerated from source with `swagger-cli bundle -t json -w 300 main.yaml` (the exact command the lint/compare-output CI job runs), so the committed bundle matches a fresh bundle of the deduped YAML. Fixes the compare-output failure introduced by editing the source without rebundling. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

jablan · 2026-06-25T13:47:42Z

+                    "type": "string",
+                    "example": "Updated landing page screenshot"
+                  },
+                  "filename": {


I think the same parameter in create endpoint has different description, also some accepted formats (no example though).
we should try to keep the same descriptions for the same parameters across endpoints, or, even better, extract them to schemas and use as references

jablan · 2026-06-25T13:48:11Z

    "$ref": "../../responses.yaml#/422"
  '429':
    "$ref": "../../responses.yaml#/429"
-x-code-samples:


why are the samples removed?

they are automatically rendered by mintlify - this removes the duplicatoin and the risk of "example drift"

just took a look. wow, those automatic examples are wrong. they are not using our generated clients at all.

I mean, probably makes sense for curl and e.g. the languages we don't cover. but others should be using our clients. I also suspect it can't generate examples for the CLI?

wow, those automatic examples are wrong
can you send an example and clarify what's wrong? "in theory" examples are generated against our spec. So my suspicion would usually be if the spec is wrong the examples are wrong or something is missing.

I wouldn't augment the scope now to the cli.

We can make a call to just keep the existing examples untoched. Or try to figure out why they are rendering so wrong.

our openapi project generates the documentation for our API, generates the CLI to work with it, but also generates client libraries for several languages. so, for example in Python, to get the information on account, one would use:

import phrase_api from phrase_api.rest import ApiException configuration = phrase_api.Configuration() api_client = phrase_api.ApiClient(configuration) api_instance = phrase_api.AccountsApi(api_client) ... api_response = api_instance.account_show('ACCOUNT_ID')

(example adapted from our python docs: https://github.com/phrase/phrase-python#getting-started)

and get a parsed response, depending on the language, cast into an appropriate structure or a class instance.

while the mintlify-generated example just performs a HTTP request to our API:

import requests url = "https://api.phrase.com/v2/accounts/{id}" headers = {"Authorization": "<api-key>"} response = requests.get(url, headers=headers)

so, more or less, a plain curl-type request.

technically, the example is not wrong, but it kinda beats a big part of the strings-openapi purpose.

I suggest we get rid of the curl examples (as they can be properly generated by mintlify), but we'd need to keep CLI examples, and potentially even expand it to other platforms we cater for (basically exposing already auto-generated platforms documentation)

New strings rubric rule: Mintlify auto-generates the request curl, so a hand-written Curl sample is redundant and overrides it, but a CLI v2 sample cannot be derived from the spec and must be preserved. This PR originally removed the whole x-code-samples block; restore the CLI v2 entry (Curl stays dropped). compiled.json regenerated via make bundle.

jablan · 2026-07-01T08:57:35Z

  required: true
  content:
-    application/json:
+    multipart/form-data:


this is a pretty significant change. although I don't doubt that it's the correct value, I'm wary how it would reflect to the generated clients (especially CLI). I suggest starting with the /create endpoint instead, and adding a CLI spec along. we want to make sure the CLI doesn't break on this change.

feat(API): improve patch /projects/{project_id}/screenshots/{id} docu…

a0f82af

…mentation

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

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 5 commits June 17, 2026 21:12

Merge branch 'main' into devex-115-screenshots-update-a-screenshot

54b3f34

Stephen Lumenta (sbl) added the breaking-change-approved Skip the oasdiff breaking-change gate: this PR intentionally changes the API surface label Jun 24, 2026

Stephen Lumenta (sbl) and others added 3 commits June 25, 2026 12:20

Merge branch 'main' into devex-115-screenshots-update-a-screenshot

84fe78a

jablan reviewed Jun 25, 2026

View reviewed changes

jablan reviewed Jul 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Stephen Lumenta (sbl) commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

Stephen Lumenta (sbl) commented Jun 24, 2026

Uh oh!

jablan Jun 25, 2026

Uh oh!

jablan Jun 25, 2026

Uh oh!

Stephen Lumenta (sbl) Jun 25, 2026

Uh oh!

jablan Jun 25, 2026

Uh oh!

jablan Jun 25, 2026

Uh oh!

Stephen Lumenta (sbl) Jun 25, 2026

Uh oh!

jablan Jun 25, 2026 •

edited

Loading

Uh oh!

jablan Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Stephen Lumenta (sbl) commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API changelog (oasdiff)

Uh oh!

Stephen Lumenta (sbl) commented Jun 24, 2026

API surface change — reviewer note

Uh oh!

jablan Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

jablan Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Stephen Lumenta (sbl) Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

jablan Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

jablan Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Stephen Lumenta (sbl) Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

jablan Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jablan Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Jun 15, 2026 •

edited

Loading

jablan Jun 25, 2026 •

edited

Loading