Validate OpenAPI definition #160
Conversation
thivindu
requested review from
DakshithaS and
malinthaprasan
and removed request for
DakshithaS
WalkthroughAdds OpenAPI validation: DTOs for request/response, a POST /validate/open-api handler and route, service method to read/validate definitions from URL or uploaded file, utility functions to fetch/parse OpenAPI 3.x and Swagger 2.0 into internal API DTO, and OpenAPI spec updates with new schemas and endpoint. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Handler as APIHandler
participant Service as APIService
participant Util as APIUtil
participant Remote as HTTP/File
Client->>Handler: POST /validate/open-api (url or file)
activate Handler
Handler->>Handler: parse multipart form (max 10MB)
Handler->>Handler: ensure url or file present
Handler->>Service: ValidateOpenAPIDefinition(request)
deactivate Handler
activate Service
alt URL provided
Service->>Util: FetchOpenAPIFromURL(url)
activate Util
Util->>Remote: HTTP GET
Remote-->>Util: payload (YAML/JSON)
Util-->>Service: []byte content
deactivate Util
else File provided
Service->>Service: read uploaded file bytes
end
Service->>Util: ParseAPIDefinition(content)
activate Util
Util->>Util: detect spec version / structure
alt OpenAPI 3.x
Util->>Util: parseOpenAPI3Document -> extractOperationsFromV3Paths
else Swagger 2.0
Util->>Util: parseSwagger2Document -> extractOperationsFromV2Paths -> convertSwagger2ToBackendServices
else Fallback
Util->>Util: parseDocumentByStructure
end
Util-->>Service: *dto.API (or error list)
deactivate Util
Service-->>Handler: *dto.OpenAPIValidationResponse
deactivate Service
Handler-->>Client: 200 OK {isAPIDefinitionValid, errors?, api?}
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🧰 Additional context used🧠 Learnings (1)📚 Learning: 2025-11-12T08:52:52.909ZApplied to files:
🧬 Code graph analysis (2)platform-api/src/internal/service/api.go (2)
platform-api/src/internal/utils/api.go (2)
🔇 Additional comments (8)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
platform-api/src/internal/dto/openapi.go(1 hunks)platform-api/src/internal/handler/api.go(2 hunks)platform-api/src/internal/service/api.go(2 hunks)platform-api/src/internal/utils/api.go(2 hunks)platform-api/src/resources/openapi.yaml(3 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: thivindu
Repo: wso2/api-platform PR: 142
File: platform-api/src/resources/openapi.yaml:905-969
Timestamp: 2025-11-12T08:52:52.909Z
Learning: In the wso2/api-platform repository, the team follows an API-first development approach where OpenAPI specs may document planned features before backend implementation is complete, allowing frontend development to proceed against the intended API contract without requiring changes later.
📚 Learning: 2025-11-08T13:06:22.133Z
Learnt from: thivindu
Repo: wso2/api-platform PR: 110
File: platform-api/src/internal/service/api.go:432-476
Timestamp: 2025-11-08T13:06:22.133Z
Learning: In the platform-api Go codebase (file: platform-api/src/internal/service/api.go), the DeployAPIRevision method is designed to automatically create API-gateway associations during deployment if they don't already exist. There is no requirement that associations must pre-exist before deployment; the system checks for existing associations and creates them on-the-fly as needed.
Applied to files:
platform-api/src/internal/service/api.go
🧬 Code graph analysis (3)
platform-api/src/internal/service/api.go (2)
platform-api/src/internal/dto/openapi.go (2)
ValidateOpenAPIRequest(27-30)OpenAPIValidationResponse(33-37)platform-api/src/internal/dto/api.go (1)
API(25-51)
platform-api/src/internal/handler/api.go (2)
platform-api/src/internal/utils/error.go (1)
NewErrorResponse(28-37)platform-api/src/internal/dto/openapi.go (1)
ValidateOpenAPIRequest(27-30)
platform-api/src/internal/utils/api.go (2)
platform-api/src/internal/dto/api.go (5)
API(25-51)Operation(134-138)OperationRequest(141-148)AuthenticationConfig(157-160)Policy(163-166)platform-api/src/internal/dto/backend_service.go (2)
BackendService(23-36)BackendEndpoint(39-45)
🔇 Additional comments (9)
platform-api/src/internal/handler/api.go (1)
771-811: LGTM! Handler implementation is solid.The multipart form handling is correct with proper file cleanup via defer, reasonable size limits, and appropriate validation. The prioritization of file over URL (when both are provided) aligns with the PR objectives.
platform-api/src/internal/dto/openapi.go (1)
1-37: LGTM! DTOs are well-structured.The request and response structures properly support both URL and file-based OpenAPI validation with clear documentation and appropriate field types.
platform-api/src/internal/service/api.go (1)
1318-1378: LGTM! Service method handles validation flow correctly.The implementation properly orchestrates URL fetching, file reading, validation, and parsing with appropriate error handling and resource cleanup.
platform-api/src/resources/openapi.yaml (2)
268-297: LGTM! Endpoint definition aligns with implementation.The OpenAPI validation endpoint is properly documented with correct request/response schemas and multipart form data handling.
2552-2634: LGTM! Schemas are well-defined.The ValidateOpenAPIRequest and OpenAPIValidationResponse schemas correctly model the validation flow with appropriate constraints (anyOf for mutual exclusivity) and field requirements.
platform-api/src/internal/utils/api.go (4)
1146-1170: LGTM! ParseAPIDefinition orchestrates parsing correctly.The method properly handles version detection and delegates to appropriate parsers for OpenAPI 3.x and Swagger 2.0 with fallback logic.
1172-1224: LGTM! OpenAPI 3.x parsing extracts metadata correctly.The method properly builds the OpenAPI 3.x model, extracts basic info, operations, and backend services from the document structure.
1226-1263: LGTM! Swagger 2.0 parsing handles legacy format correctly.The method appropriately builds the Swagger 2.0 model and converts host/basePath/schemes to backend services.
1291-1397: LGTM! Operation extraction handles all HTTP methods.Both V3 and V2 path extraction methods correctly iterate through path items and extract operations for all supported HTTP methods.
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
platform-api/src/internal/utils/api.go (2)
1295-1347: Consider generating default names for operations with empty summaries.If
operation.Summaryis empty, the resulting operation will have an emptyNamefield. This could cause issues in the UI or downstream processing.Consider generating a default name from the method and path:
+ operationName := operation.Summary + if operationName == "" { + operationName = fmt.Sprintf("%s %s", method, path) + } + op := dto.Operation{ - Name: operation.Summary, + Name: operationName, Description: operation.Description,
1349-1401: Consider generating default names for operations with empty summaries.Same issue as
extractOperationsFromV3Paths: ifoperation.Summaryis empty, the operation will have an emptyNamefield.Apply the same fix as suggested for the V3 version:
+ operationName := operation.Summary + if operationName == "" { + operationName = fmt.Sprintf("%s %s", method, path) + } + op := dto.Operation{ - Name: operation.Summary, + Name: operationName, Description: operation.Description,
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
platform-api/src/internal/utils/api.go(2 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: thivindu
Repo: wso2/api-platform PR: 142
File: platform-api/src/resources/openapi.yaml:905-969
Timestamp: 2025-11-12T08:52:52.909Z
Learning: In the wso2/api-platform repository, the team follows an API-first development approach where OpenAPI specs may document planned features before backend implementation is complete, allowing frontend development to proceed against the intended API contract without requiring changes later.
🧬 Code graph analysis (1)
platform-api/src/internal/utils/api.go (2)
platform-api/src/internal/dto/api.go (5)
API(25-51)Operation(134-138)OperationRequest(141-148)AuthenticationConfig(157-160)Policy(163-166)platform-api/src/internal/dto/backend_service.go (2)
BackendService(23-36)BackendEndpoint(39-45)
🔇 Additional comments (3)
platform-api/src/internal/utils/api.go (3)
1127-1148: LGTM! Timeout and error handling implemented correctly.The previous feedback regarding timeout has been addressed. The function now uses a 30-second timeout and properly handles errors and response reading.
1150-1174: LGTM! Well-structured parsing entry point.The version-based routing with a fallback mechanism is a good approach for handling different OpenAPI/Swagger versions.
1269-1293: LGTM! Robust fallback mechanism.The function correctly attempts both OpenAPI 3.x and Swagger 2.0 parsing and provides clear error messages if both fail.
| return response, nil | ||
| } | ||
|
|
||
| response.IsAPIDefinitionValid = true |
There was a problem hiding this comment.
Sets IsAPIDefinitionValid: true after successful syntax validation.
However, if metadata parsing fails, it still returns true but includes error details.
| content, err = s.apiUtil.FetchOpenAPIFromURL(req.URL) | ||
| if err != nil { | ||
| response.Errors = append(response.Errors, fmt.Sprintf("failed to fetch OpenAPI from URL: %s", err.Error())) | ||
| return response, nil |
There was a problem hiding this comment.
When both URL and file are provided, the logic stops and returns immediately if the URL fetch fails, without attempting to read from the file.
3 participants
Purpose
The Management Portal requires API creation via Contract Flow via URL and OpenAPI definition file upload. Therefore, the provided OpenAPI definition needs to be validated, parsed and the API metadata needs to sent to the frontend.
Fixes: wso2/api-platform/issues#159
Goals
Validate and parse the provided API definition.
Approach
This pull request introduces a new endpoint for validating OpenAPI definitions via file upload or URL, along with the necessary backend logic and OpenAPI documentation updates. The main goal is to allow users to validate OpenAPI specs and extract API metadata through a unified interface.
Key changes include:
API Endpoint and Handler
/api/v1/validate/open-apithat accepts multipart form data, allowing users to upload an OpenAPI definition file or provide a URL. The handler prioritizes the file if both are provided and returns validation results and extracted metadata. [1] [2]DTOs and Service Logic
ValidateOpenAPIRequestandOpenAPIValidationResponseDTOs to represent the request and response for OpenAPI validation, supporting both file and URL inputs and encapsulating validation results and extracted API details.ValidateOpenAPIDefinitionin the service layer to handle fetching/parsing the OpenAPI content, validating it, and extracting API metadata usinglibopenapi.Utility Enhancements
OpenAPI Specification Updates
/validate/open-apiendpoint, including request/response schemas, in the OpenAPI YAML. Defined theValidateOpenAPIRequestandOpenAPIValidationResponseschemas to match the new API. [1] [2] [3]These changes provide a robust and user-friendly way to validate OpenAPI definitions and extract relevant API information through the platform API.
Summary by CodeRabbit