Define common schema for query parameters and list response#574
Define common schema for query parameters and list response#574
Conversation
|
@copilot retry |
Co-authored-by: miacycle <184569369+miacycle@users.noreply.github.com>
I've completed the implementation. The common schemas for query parameters and list responses have been added to What was added:
These can now be referenced by any API specification to ensure consistency. See commit 6ef6508. |
There was a problem hiding this comment.
Pull request overview
This PR introduces standardized, reusable schemas for query parameters and pagination responses to promote consistency across Meshery API endpoints. It adds properly typed parameters with validation constraints and a pagination metadata schema for list responses.
Changes:
- Added
paginationMetadataschema with page, page_size, and total_count properties for standardized list responses - Defined five standardized query parameters (pageNumber, pageSize, sortOrder, searchQuery, filterQuery) with proper integer types and validation
- Created comprehensive documentation in COMMON_SCHEMAS.md with usage examples and migration guide
- Updated .gitignore to exclude generated Go and TypeScript code directories
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| schemas/constructs/v1alpha1/core/api.yml | Adds paginationMetadata schema and five standardized query parameters with proper types and validation |
| schemas/constructs/v1alpha1/core/COMMON_SCHEMAS.md | Provides detailed documentation, usage examples, and migration guidance for the new common schemas |
| .gitignore | Excludes generated models/ and typescript/generated/ directories |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| pageNumber: | ||
| name: page | ||
| in: query | ||
| description: Page number for pagination (1-indexed). Returns the specified page of results. | ||
| schema: | ||
| type: integer | ||
| minimum: 1 | ||
| default: 1 | ||
| required: false |
There was a problem hiding this comment.
The new 'pageNumber' parameter uses the name 'page', which conflicts with the existing legacy 'page' parameter at line 921-926. Both parameters share the same query parameter name ('page') but have different types (integer vs string). This creates ambiguity and may cause issues when both parameters are referenced in the same OpenAPI specification. Consider using a different name for the new parameter or documenting that the legacy parameter should be removed when migrating to the new standardized parameter.
| pageSize: | ||
| name: pagesize | ||
| in: query | ||
| description: Number of items to return per page. Maximum value is 100. | ||
| schema: | ||
| type: integer | ||
| minimum: 1 | ||
| maximum: 100 | ||
| default: 25 | ||
| required: false |
There was a problem hiding this comment.
The new 'pageSize' parameter uses the name 'pagesize', which conflicts with the existing legacy 'pagesize' parameter at line 945-950. Both parameters share the same query parameter name ('pagesize') but have different types (integer vs string). This creates ambiguity and may cause issues when both parameters are referenced in the same OpenAPI specification. Consider using a different name for the new parameter or documenting that the legacy parameter should be removed when migrating to the new standardized parameter.
| sortOrder: | ||
| name: order | ||
| in: query | ||
| description: Sort order for results. Use 'asc' for ascending or 'desc' for descending. | ||
| schema: | ||
| type: string | ||
| enum: [asc, desc] | ||
| default: desc | ||
| required: false |
There was a problem hiding this comment.
The new 'sortOrder' parameter uses the name 'order', which conflicts with the existing legacy 'order' parameter at line 957-962. Both parameters share the same query parameter name ('order') but have different types and constraints (enum with asc/desc vs plain string). This creates ambiguity and may cause issues when both parameters are referenced in the same OpenAPI specification. Consider using a different name for the new parameter or documenting that the legacy parameter should be removed when migrating to the new standardized parameter.
| searchQuery: | ||
| name: search | ||
| in: query | ||
| description: Search query string to filter results. Searches across relevant fields of the resource. | ||
| schema: | ||
| type: string | ||
| required: false |
There was a problem hiding this comment.
The new 'searchQuery' parameter uses the name 'search', which conflicts with the existing legacy 'search' parameter at line 975-980. Both parameters share the same query parameter name ('search') but may have different contexts or documentation. This creates ambiguity when both parameters are referenced in the same OpenAPI specification. Consider using a different name for the new parameter or documenting that the legacy parameter should be removed when migrating to the new standardized parameter.
| filterQuery: | ||
| name: filter | ||
| in: query | ||
| description: Filter query to narrow down results based on specific criteria. | ||
| schema: | ||
| type: string | ||
| required: false |
There was a problem hiding this comment.
The new 'filterQuery' parameter uses the name 'filter', which conflicts with the existing legacy 'filter' parameter at line 981-986. Both parameters share the same query parameter name ('filter') but may have different contexts or documentation. This creates ambiguity when both parameters are referenced in the same OpenAPI specification. Consider using a different name for the new parameter or documenting that the legacy parameter should be removed when migrating to the new standardized parameter.
This PR defines reusable common schemas for query parameters and list responses to promote consistency across all API endpoints in the Meshery schemas repository.
Changes Made
1. Common Query Parameters
Added standardized query parameters in
schemas/constructs/v1alpha1/core/api.yml:pageNumber- Page number for pagination (integer, 1-indexed, min: 1, default: 1)pageSize- Number of items per page (integer, min: 1, max: 100, default: 25)sortOrder- Sort order (enum: asc/desc, default: desc)searchQuery- Search query stringfilterQuery- Filter query stringThese replace the less specific legacy parameters (which are kept for backward compatibility) and provide proper type definitions, validation constraints, better documentation, and default values.
2. Pagination Metadata Schema
Added
paginationMetadataschema for consistent pagination information in list responses with properties:page(integer, 1-indexed),page_size(integer, 1-100), andtotal_count(integer, 0+). This can be referenced directly or composed withallOfto create resource-specific page responses.3. Documentation
Created
COMMON_SCHEMAS.mdwith detailed documentation of each parameter and schema, usage examples for API endpoints, migration guide from old to new patterns, and benefits and best practices.4. Build Configuration
Updated
.gitignoreto exclude generated files:models/directory (generated Go code) andtypescript/generated/directory (generated TypeScript).Benefits
Testing
Original prompt
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.