fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation #1190
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,19 @@ | ||
| --- | ||
| summary: Update a screenshot | ||
| description: | | ||
| Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource. | ||
|
|
||
| Use this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one. | ||
|
|
||
| The name must be unique within the project (case-insensitive). Existing screenshot markers are unaffected unless marker attributes are explicitly passed. | ||
| operationId: screenshot/update | ||
| tags: | ||
| - Screenshots | ||
| parameters: | ||
| - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" | ||
| - "$ref": "../../parameters.yaml#/project_id" | ||
| - "$ref": "../../parameters.yaml#/id" | ||
| x-code-samples: | ||
|
Collaborator
There was a problem hiding this comment. why are the samples removed?
Contributor
Author
There was a problem hiding this comment. they are automatically rendered by mintlify - this removes the duplicatoin and the risk of "example drift"
Collaborator
There was a problem hiding this comment. just took a look. wow, those automatic examples are wrong. they are not using our generated clients at all.
Collaborator
There was a problem hiding this comment. I mean, probably makes sense for
Contributor
Author
There was a problem hiding this comment.
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.
Collaborator
There was a problem hiding this comment. 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) |
||
| - lang: CLI v2 | ||
| source: |- | ||
| phrase screenshots update \ | ||
|
|
@@ -55,7 +24,7 @@ x-code-samples: | |
| requestBody: | ||
| required: true | ||
| content: | ||
| multipart/form-data: | ||
|
Collaborator
There was a problem hiding this comment. 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 |
||
| schema: | ||
| type: object | ||
| title: screenshot/update/parameters | ||
|
|
@@ -65,16 +34,43 @@ requestBody: | |
| type: string | ||
| example: my-feature-branch | ||
| name: | ||
| description: New display name for the screenshot. Must be non-empty and unique within the project (case-insensitive). Omit to leave the current name unchanged. | ||
| type: string | ||
| minLength: 1 | ||
| example: home_screen_v2 | ||
| description: | ||
| description: Updated description for the screenshot. Omit to leave the current description unchanged. | ||
| type: string | ||
| example: Updated landing page screenshot | ||
| filename: | ||
| description: Screenshot file | ||
| type: string | ||
| format: binary | ||
| example: "/path/to/my/screenshot.png" | ||
| responses: | ||
| '200': | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| "$ref": "../../schemas/screenshot.yaml#/screenshot" | ||
| headers: | ||
| X-Rate-Limit-Limit: | ||
| "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" | ||
| X-Rate-Limit-Remaining: | ||
| "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" | ||
| X-Rate-Limit-Reset: | ||
| "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" | ||
| '400': | ||
| "$ref": "../../responses.yaml#/400" | ||
| '401': | ||
| "$ref": "../../responses.yaml#/401" | ||
| '403': | ||
| "$ref": "../../responses.yaml#/403" | ||
| '404': | ||
| "$ref": "../../responses.yaml#/404" | ||
| '422': | ||
| "$ref": "../../responses.yaml#/422" | ||
| '429': | ||
| "$ref": "../../responses.yaml#/429" | ||
| x-cli-version: '2.5' | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the same parameter in
createendpoint 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