feat: enhance workspace and environment API schemas with comprehensive documentation#546
Conversation
…e documentation Signed-off-by: 1012Charan <charanvengala@gmail.com>
Summary of ChangesHello @1012Charan, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly upgrades the OpenAPI schemas for Meshery's workspace and environment constructs. The primary goal is to provide a much richer and more consistent API documentation experience by adding extensive descriptions to endpoints, standardizing error handling, and improving parameter definitions. These changes aim to make the API more intuitive and easier for developers to understand and integrate with, ultimately enhancing the overall developer experience. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the OpenAPI schemas for the workspace and environment APIs. The documentation for endpoints, parameters, and schemas is now much more comprehensive, which is a great improvement for API consumers. The error responses have also been standardized.
My review includes a few suggestions to improve API consistency. Specifically, for both environment and workspace resources, the GET operation for a single resource includes an orgIDQuery parameter for scoping, but the PUT and DELETE operations do not. While PUT includes the organization ID in the body, DELETE has no organization scope in the request at all. I've suggested adding the orgIDQuery parameter to these operations for consistency and to strengthen the security posture by explicitly scoping all requests.
| parameters: | ||
| - $ref: "#/components/parameters/environmentId" |
There was a problem hiding this comment.
For consistency with the get operation on this path, consider adding the orgIDQuery parameter here as well. While the organization_id is present in the request body, having the organization scope in the query parameters for all single-resource operations improves API consistency and can simplify routing and initial authorization logic.
parameters:
- $ref: "#/components/parameters/environmentId"
- $ref: "#/components/parameters/orgIDQuery"| parameters: | ||
| - $ref: "#/components/parameters/environmentId" |
There was a problem hiding this comment.
For consistency and improved security, it's recommended to add the orgIDQuery parameter to this delete operation. The get operation for a single environment includes it, and requiring it here would ensure that all operations on a specific environment are explicitly scoped to an organization in the request itself. This prevents the backend from having to look up the resource just to determine its parent organization for authorization checks.
parameters:
- $ref: "#/components/parameters/environmentId"
- $ref: "#/components/parameters/orgIDQuery"| parameters: | ||
| - name: id | ||
| in: path | ||
| required: true | ||
| schema: | ||
| type: string | ||
| - $ref: "#/components/parameters/workspaceId" |
There was a problem hiding this comment.
For consistency with the get operation on this path, consider adding the orgIDQuery parameter here as well. While the organization_id is present in the request body, having the organization scope in the query parameters for all single-resource operations improves API consistency and can simplify routing and initial authorization logic.
parameters:
- $ref: "#/components/parameters/workspaceId"
- $ref: "#/components/parameters/orgIDQuery"| parameters: | ||
| - name: id | ||
| in: path | ||
| required: true | ||
| schema: | ||
| type: string | ||
| - $ref: "#/components/parameters/workspaceId" |
There was a problem hiding this comment.
For consistency and improved security, it's recommended to add the orgIDQuery parameter to this delete operation. The get operation for a single workspace includes it, and requiring it here would ensure that all operations on a specific workspace are explicitly scoped to an organization in the request itself. This prevents the backend from having to look up the resource just to determine its parent organization for authorization checks.
parameters:
- $ref: "#/components/parameters/workspaceId"
- $ref: "#/components/parameters/orgIDQuery"
| "401": | ||
| $ref: "#/components/responses/401" | ||
| "500": | ||
| $ref: "#/components/responses/500" |
There was a problem hiding this comment.
Let's be sure to document our MeshKit error schema, then come back to make a reference in each of these.
| - $ref: "#/components/parameters/filter" | ||
| responses: | ||
| "200": | ||
| description: Successfully retrieved environments list |
There was a problem hiding this comment.
Remove "successfully" from all aspects of this schema.
Signed-off-by: 1012Charan <charanvengala@gmail.com>
2 participants
Description
This PR enhances the OpenAPI schemas for workspace and environment constructs in
schemas/constructs/v1beta1. It addresses gaps in API documentation by adding comprehensive descriptions, standardizing error responses, and improving schema definitions.Changes
Workspace Construct (v1beta1/workspace)
/api/workspaces (Create, List workspaces)
/api/workspaces/{workspaceId} (Get, Update, Delete)
/api/workspaces/{workspaceId}/environments (Manage Environment bindings)
/api/workspaces/{workspaceId}/designs (Manage Design bindings)
Environment Construct (
environment/v1beta1)/api/environments (Create, List environments)
/api/environments/{environmentId} (Get, Update, Delete)
/api/environments/{environmentId}/connections (Manage Connection bindings)
This PR fixes #545
Signed commits