Alexey Serbin has submitted this change and it was merged. ( http://gerrit.cloudera.org:8080/23224 )
Change subject: Add OpenAPI specification for REST API endpoints ...................................................................... Add OpenAPI specification for REST API endpoints Create a hand-written swagger/kudu-api.json specification rather than implementing automated generation infrastructure. This approach was chosen for several practical reasons: - Kudu's REST API currently has only 3 main endpoints (/api/v1/tables, /api/v1/tables/<table_id>, /api/v1/leader) with ~5 total method/path combinations. The overhead of automated generation (C++ fluent APIs, annotation parsers, or complex macros) would exceed the maintenance burden of manual updates. - These endpoints are relatively stable and not changing frequently, reducing the risk of documentation drift. - A single JSON file is easier to review, debug, and modify than custom C++ infrastructure or parsing scripts. - No additional build steps, external tools, or runtime overhead. The specification is immediately available when the server starts. - If the API grows significantly or changes frequently, we can revisit automated generation. The OpenAPI 3.0 specification includes complete documentation for all current endpoints with request/response schemas, parameter validation, and error codes. It's served at /swagger/kudu-api.json and integrates with the existing Swagger UI at /api/docs. A Jira has been created for adding an automatic validation script (https://issues.apache.org/jira/browse/KUDU-3700). Change-Id: I3981665c78f478e89d0300f3a2fc5d68b73b8762 Reviewed-on: http://gerrit.cloudera.org:8080/23224 Reviewed-by: Alexey Serbin <[email protected]> Tested-by: Alexey Serbin <[email protected]> --- M src/kudu/master/CMakeLists.txt M src/kudu/master/rest_catalog-test.cc M src/kudu/master/rest_catalog_path_handlers.cc M src/kudu/master/rest_catalog_path_handlers.h A www/api/docs.mustache A www/swagger/kudu-api.json A www/swagger/kudu-custom.css A www/swagger/kudu-swagger-init.js A www/swagger/swagger-ui-bundle.js A www/swagger/swagger-ui.css 10 files changed, 1,235 insertions(+), 1 deletion(-) Approvals: Alexey Serbin: Looks good to me, approved; Verified -- To view, visit http://gerrit.cloudera.org:8080/23224 To unsubscribe, visit http://gerrit.cloudera.org:8080/settings Gerrit-Project: kudu Gerrit-Branch: master Gerrit-MessageType: merged Gerrit-Change-Id: I3981665c78f478e89d0300f3a2fc5d68b73b8762 Gerrit-Change-Number: 23224 Gerrit-PatchSet: 11 Gerrit-Owner: Gabriella Lotz <[email protected]> Gerrit-Reviewer: Alexey Serbin <[email protected]> Gerrit-Reviewer: Gabriella Lotz <[email protected]> Gerrit-Reviewer: Kudu Jenkins (120) Gerrit-Reviewer: Marton Greber <[email protected]> Gerrit-Reviewer: Zoltan Chovan <[email protected]>
