[
https://issues.apache.org/jira/browse/KUDU-3700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18059909#comment-18059909
]
ASF subversion and git services commented on KUDU-3700:
-------------------------------------------------------
Commit d3802e7e5761d206a1793c3d3165d1bc754134d8 in kudu's branch
refs/heads/master from Gabriella Lotz
[ https://gitbox.apache.org/repos/asf?p=kudu.git;h=d3802e7e5 ]
KUDU-3700 Add swagger verification script docs
Document usage and expected output for the swagger verification helper to
make it easy to run manually and possibly in CI.
Manual testing:
- ./build-support/verify_swagger_spec.py
- Manual negative checks by temporarily changing swagger path/method/param
confirmed mismatch output
Examples:
- Path coverage: swagger paths (with server base /api/v1) must match
registered /api/... handlers in source.
Swagger verification failed with 2 issue(s):
- Swagger path missing in source: /api/v1/leaders
- Source path missing in swagger: /api/v1/leader
- HTTP methods: methods inferred from req.request_method checks must match
swagger operations.
Swagger verification failed with 2 issue(s):
- Swagger missing methods for /api/v1/tables: POST
- Swagger has extra methods for /api/v1/tables: PUT
- Path parameters: swagger path params must match <param> names in the
handler path.
Swagger verification failed with 1 issue(s):
- Parameter mismatch for GET /api/v1/tables/{table_id}:
swagger=['table_uuid'] source=['table_id']
Change-Id: I3ca60becef11eb2170544f87fafc5d9aa4110a31
Reviewed-on: http://gerrit.cloudera.org:8080/23904
Reviewed-by: Marton Greber <[email protected]>
Tested-by: Marton Greber <[email protected]>
Reviewed-by: Alexey Serbin <[email protected]>
> Add validation for manual OpenAPI specification
> -----------------------------------------------
>
> Key: KUDU-3700
> URL: https://issues.apache.org/jira/browse/KUDU-3700
> Project: Kudu
> Issue Type: Improvement
> Reporter: Gabriella Lotz
> Assignee: Gabriella Lotz
> Priority: Major
>
> h2. Problem
> The hand-written swagger/kudu-api.json file could drift out of sync with the
> actual REST API source code, leading to inaccurate documentation.
> h2. Solution
> Create a verification script that cross-checks the swagger.json against REST
> API source code to catch inconsistencies early. This maintains the current
> manual approach while adding safety validation.
> h2. Alternative considered
> Full automation by generating swagger from source code, but this would be
> more intrusive and exceeds current scope.
> h2. Acceptance Criteria
> - Script validates endpoint paths, HTTP methods, and parameters match
> between swagger.json and source
> - Script provides clear error messages for inconsistencies
> - Can be run manually and integrated into CI pipeline
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
