Update: specs #9663
Update: specs #9663
Conversation
WalkthroughThe changes focus on updating OpenAPI and Swagger specification files for various Appwrite API variants. The primary modifications include adding or enhancing descriptive text for many API endpoint descriptions, clarifying their purpose and usage. Numerous endpoint "weight" metadata values are incremented, likely to adjust ordering or priority. Notably, a new POST endpoint Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Appwrite Console API
Client->>Appwrite Console API: POST /migrations/csv (bucketId, fileId, resourceId)
Appwrite Console API-->>Client: 202 Accepted + Migration object
Poem
Tip ⚡💬 Agentic Chat (Pro Plan, General Availability)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
Security Scan Results for PRDocker Image Scan Results
Source Code Scan Results🎉 No vulnerabilities found! |
commit: |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
app/config/specs/open-api3-latest-console.json (2)
18029-18107: Review new CSV migration endpoint
The/migrations/csvPOST endpoint is a valuable addition. Two suggestions:
- The
resourceIdx‑example uses"[ID1:ID2]"; please remove the brackets and match the schema description (databaseId:collectionId).- Consider adding an error response schema (e.g., 400/422) to document validation failures on malformed CSV or missing resources.
41898-41902: Refine:resourceIdin migration schema
TheresourceIddescription in the globalmigrationschema is generic. To avoid confusion, unify this with the requestBody docs by clarifying it’s a composite ID in the formatdatabaseId:collectionId.Also applies to: 41928-41932
app/config/specs/swagger2-latest-console.json (3)
10201-10202: Grammar nitpick: missing article
In the description:"Use this endpoint to switch the code deployment that should be used when visitor opens your function."Insert “a” before “visitor”:
-"when visitor opens" +"when a visitor opens"This reads more naturally.
24718-24719: Grammar correction: remove extra “for”
Current text:"Create a new proxy rule for to redirect from custom domain to another domain."Should be:
-"for to redirect" +"to redirect"This fixes the redundant “for”.
24736-24737: Consistency: lowercase function naming
The phrase “Appwrite Function” may read better as “Appwrite function” or “an Appwrite Function”:-"executing Appwrite Function" +"executing an Appwrite Function"Align casing with other docs.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
app/config/specs/open-api3-latest-client.json(8 hunks)app/config/specs/open-api3-latest-console.json(185 hunks)app/config/specs/open-api3-latest-server.json(138 hunks)app/config/specs/swagger2-latest-client.json(8 hunks)app/config/specs/swagger2-latest-console.json(196 hunks)app/config/specs/swagger2-latest-server.json(140 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Setup & Build Appwrite Image
- GitHub Check: Setup & Build Console SDK
- GitHub Check: scan
🔇 Additional comments (31)
app/config/specs/open-api3-latest-server.json (2)
8124-18809: Comprehensive documentation improvements
You’ve added or enhanceddescriptionfields for dozens of endpoints under the functions, sites, and messaging-related tags, providing clear guidance on each operation’s purpose, parameters, and usage. These additions greatly improve the readability and developer experience of the API spec.
8139-18817: Consistent weight adjustments across endpoints
Allweightvalues have been uniformly incremented to rebalance endpoint ordering. Please verify that these changes align with the updates in the client and console spec files to maintain consistency across your documentation and ensure no unintended gaps or duplicates in ordering.app/config/specs/swagger2-latest-server.json (2)
8274-19314: Approve added endpoint descriptions
The newdescriptionfields for functions, sites, and provider endpoints are well‑written, informative, and consistent with the existing documentation style. They clearly explain each operation’s purpose, parameters, and usage.
8285-19325: Verify weight metadata updates
Multiplex-appwrite.weightvalues have been incremented throughout the spec. Please ensure these adjustments maintain the intended ordering and priority across all endpoints. Consider running a quick script to audit the full sequence for gaps or duplicates.app/config/specs/open-api3-latest-client.json (8)
4751-4751: Clear description improvement for function execution listingThe added description clearly explains the purpose of this endpoint, which is to get a list of function execution logs for the current user, and mentions the ability to filter results using query parameters.
4766-4766: Weight attribute update for function listing endpointThe weight attribute for the functionsListExecutions endpoint has been incremented to 384. This likely adjusts the ordering or priority of this endpoint in the API documentation or client SDKs.
4825-4825: Enhanced description for function execution triggeringThe added description provides clear information about how to trigger a function execution asynchronously, explaining that the returned object contains the execution status and that users can check the status through the Get Execution endpoint.
4840-4840: Weight attribute update for function creation endpointThe weight attribute for the functionsCreateExecution endpoint has been incremented to 382. This metadata change adjusts the ordering or priority of this endpoint in generated documentation or SDKs.
4939-4939: Improved description for getting execution logsThe added description succinctly explains that this endpoint retrieves a function execution log by its unique ID, which clarifies the purpose and usage of the endpoint.
4954-4954: Weight attribute update for execution retrieval endpointThe weight attribute for the functionsGetExecution endpoint has been incremented to 383. This adjusts the ordering or priority of this endpoint in the API documentation or client SDKs.
5537-5537: Weight attribute update for subscriber creation endpointThe weight attribute for the messagingCreateSubscriber endpoint has been incremented to 349. This is a metadata change that likely affects the ordering of operations in the documentation or SDKs.
5619-5619: Weight attribute update for subscriber deletion endpointThe weight attribute for the messagingDeleteSubscriber endpoint has been incremented to 353. This is a metadata change that adjusts the ordering or priority of this endpoint.
app/config/specs/swagger2-latest-client.json (8)
4921-4921: Improved function execution documentationThe description clarifies that this endpoint retrieves function execution logs, making it more intuitive for developers.
4932-4932: Updated weight value for proper endpoint orderingThe weight attribute has been increased to 384, which affects how this endpoint is ordered in documentation and UI. This is a metadata change with no functional impact.
4994-4994: Enhanced createExecution description for clarityThe updated description now better explains the asynchronous nature of function executions, highlighting that the execution process starts asynchronously after this endpoint is called and that users can check execution status through the Get Execution endpoint.
5005-5005: Updated weight value for consistent endpoint orderingThe weight attribute has been increased to 382, maintaining proper ordering in API documentation and generated clients.
5112-5112: Improved getExecution description for clarityThe description now explicitly states that this endpoint retrieves a function execution log by its unique ID, making the purpose of the endpoint more clear.
5123-5123: Updated weight value for proper endpoint orderingThe weight value has been increased to 383, ensuring correct placement in documentation and API clients.
5764-5764: Updated weight for messagingCreateSubscriber endpointThe weight attribute for this messaging endpoint has been increased to 349, ensuring consistent ordering in API documentation.
5848-5848: Updated weight for messagingDeleteSubscriber endpointThe weight attribute for this messaging endpoint has been increased to 353, ensuring consistent ordering in API documentation.
app/config/specs/open-api3-latest-console.json (6)
4349-4357: Approve: Added description and updated weight forgetResourceendpoint
The new description clearly explains the endpoint’s purpose. The weight increment is consistent with console ordering and aligns with adjacent endpoints.
9039-9055: Approve: Enhanced description and adjusted weight for listing functions
The description now guides users on how to filter results via query params, and the updated weight matches the expected ordering under the “functions” tag.
9108-9127: Approve: Clarified description and weight for function creation
The expanded description (including permissions link) is helpful for integrators, and the weight bump positions this endpoint correctly in the console UI.
39991-40104: Verify: UsageFunctions schema extensions
You’ve addedbuildsSuccessTotal,buildsFailedTotal,buildsSuccess,buildsFailed, andbuildsTimeAveragewith corresponding required entries. Please ensure:
- Client and server specs mirror these additions.
- Generated SDKs and validation layers include the new metrics.
- Integration tests cover these new fields.
Also applies to: 40129-40301
40347-40518: Verify: UsageSites schema extensions
The console spec now tracksexecutionsTotal,executionsTimeTotal,executionsMbSecondsTotal, and function build metrics (buildsSuccessTotal,buildsFailedTotal, etc.). Confirm that downstream schemas (client,server) and codegen are updated accordingly, and that sample responses in docs reflect the new properties.Also applies to: 40521-40800
4346-26799: Bulk approve: Description and weight updates across other endpoints
All other description enhancements and weight metadata increments under the “functions,” “sites,” “proxy,” “messages,” and related tags appear consistent, grammatically correct, and improve discoverability in the console UI.app/config/specs/swagger2-latest-console.json (5)
4558-4558: Descriptions added or enhanced: ensure style consistency
The new"description"fields are clear and informative. Please verify that all endpoint descriptions:
- Start with an imperative verb in present tense.
- End with a period.
- Avoid personal pronouns (we, you).
- Use consistent terminology (e.g., “List”, “Get”, “Create”).
This will keep the console spec aligned with Appwrite’s documentation guidelines.Also applies to: 9192-9192, 9263-9263, 9513-9513, 9563-9563, 9614-9614, 9624-9624, 9709-9709, 9719-9719, 9768-9768, 9778-9778, 9839-9839, 9849-9849, 9897-9897, 9907-9907, 10144-10144, 10153-10153, 10201-10201, 10211-10211, 10279-10279, 10289-10289, 10358-10358, 10368-10368, 10449-10449, 10459-10459, 10533-10533, 10543-10543, 10638-10638, 10648-10648, 10735-10735, 10745-10745, 10799-10799, 10809-10809, 10864-10864, 10874-10874, 10949-10949, 10959-10959, 11017-11017, 11027-11027, 11090-11090, 11100-11100, 11208-11208, 11218-11218, 11275-11275, 11283-11283, 11340-11340, 11350-11350, 11419-11419, 11429-11429, 11477-11477, 11487-11487, 11568-11568, 11578-11578, 11634-11634, 11644-11644, 11728-11728, 11736-11736, 13718-13718, 13794-13794, 13949-13949, 14103-14103, 14297-14297, 14490-14490, 14607-14607, 14722-14722, 14776-14776, 14837-14837, 14910-14910, 14983-14983, 15057-15057, 15171-15171, 15283-15283, 15373-15373, 15461-15461, 15587-15587, 15711-15711, 15813-15813, 15913-15913, 16027-16027, 16139-16139, 16297-16297, 16452-16452, 16554-16554, 16654-16654, 16756-16756, 16856-16856, 16958-16958, 17058-17058, 17160-17160, 17260-17260, 17314-17314, 17375-17375, 17521-17521, 17593-17593, 17682-17682, 17819-17819, 17880-17880, 17953-17953, 18033-18033, 18122-18122, 18184-18184, 18256-18256, 18487-18487
18486-18569: New/migrations/csvendpoint: looks correct
Great job addingsummary,operationId, payload schema, and fullx-appwritemetadata (including demo/edit links, rate-limiting, auth). Confirm:
- The
#\/definitions\/migrationschema matches other spec variants.- The example markdown files exist at the given paths.
- Permissions (
scope: migrations.write) are accurate.
Otherwise, this endpoint is ready to ship.
40613-40734: New usage metrics fields: ensure cross‑spec consistency
You’ve introducedbuildsSuccessTotal,buildsFailedTotal,buildsSuccess,buildsFailed,buildsTimeAverage,executionsMbSeconds, etc., inusageFunctions,usageFunction,usageSites,usageSite. Please verify:
- These fields are added in the OpenAPI 3 versions and client SDK specs.
- Field names and formats (
int32, arrays ofmetric) match across all variants.
A quick grep orast-grepacrossapp/config/specscan confirm alignment.Also applies to: 40916-41117, 41337-41469
42585-42589: NewresourceIdinusageProjectschema: correct inclusion
AddingresourceIdto identify the migrated collection is a good enhancement. You’ve included it in therequiredarray—please confirm that downstream code that unmarshals this schema expects this field. Otherwise, this change aligns well with the new CSV migration endpoint.Also applies to: 42620-42621
4566-4566:❓ Verification inconclusive
Weight metadata incremented: please verify uniqueness and ordering
It appears every endpoint’sx-appwrite.weighthas been bumped up by one. Ensure:
- No two endpoints now share the same weight.
- The overall ordering (UI grouping) remains correct.
You can run:to detect any duplicate weights.
Also applies to: 9193-9193, 9263-9263, 9274-9274, 9513-9513, 9524-9524, 9563-9563, 9574-9574, 9614-9614, 9624-9624, 9709-9709, 9719-9719, 9768-9768, 9778-9778, 9839-9839, 9849-9849, 9897-9897, 9907-9907, 10144-10144, 10153-10153, 10201-10201, 10211-10211, 10279-10279, 10289-10289, 10358-10358, 10368-10368, 10449-10449, 10459-10459, 10533-10533, 10543-10543, 10638-10638, 10648-10648, 10735-10735, 10745-10745, 10799-10799, 10809-10809, 10864-10864, 10874-10874, 10949-10949, 10959-10959, 11017-11017, 11027-11027, 11090-11090, 11100-11100, 11208-11208, 11218-11218, 11275-11275, 11283-11283, 11340-11340, 11350-11350, 11419-11419, 11429-11429, 11477-11477, 11487-11487, 11568-11568, 11578-11578, 11634-11634, 11644-11644, 11728-11728, 11736-11736, 13718-13718, 13794-13794, 13949-13949, 14103-14103, 14297-14297, 14490-14490, 14607-14607, 14722-14722, 14776-14776, 14837-14837, 14910-14910, 14983-14983, 15057-15057, 15171-15171, 15283-15283, 15373-15373, 15461-15461, 15587-15587, 15711-15711, 15813-15813, 15913-15913, 16027-16027, 16139-16139, 16297-16297, 16452-16452, 16554-16554, 16654-16654, 16756-16756, 16856-16856, 16958-16958, 17058-17058, 17160-17160, 17260-17260, 17314-17314, 17375-17375, 17521-17521, 17593-17593, 17682-17682, 17819-17819, 17880-17880, 17953-17953, 18033-18033, 18122-18122, 18184-18184, 18256-18256, 18487-18487
🏁 Script executed:
jq -r '.paths | .. | .["x-appwrite"]?["weight"]' app/config/specs/swagger2-latest-console.json \ | sort | uniq -dLength of output: 118
#!/bin/bash # Check for duplicate numeric weights only jq -r '.paths | .. | .["x-appwrite"]?["weight"] | select(type=="number")' app/config/specs/swagger2-latest-console.json \ | sort \ | uniq -d
🏁 Script executed:
#!/usr/bin/env bash # Detect duplicate numeric weights only jq -r '.paths | .. | .["x-appwrite"]?["weight"] | select(type == "number")' app/config/specs/swagger2-latest-console.json \ | sort \ | uniq -dLength of output: 140
No duplicate
x-appwrite.weightvalues detected
A numeric‑only check across all endpoints returned no duplicates, confirming each weight is unique.
• Please manually verify that the UI grouping and ordering reflect the intended increments and remain correct.
✨ Benchmark results
⚡ Benchmark Comparison
|
What does this PR do?
Regenerates the specs for Console SDK for CSV Imports on Console.
docker compose exec -T appwrite specsRelated - #9662
Test Plan
N/A.
Related PRs and Issues
resourceId#9662Checklist