Hello Marton Greber, Zoltan Chovan, Alexey Serbin, Kudu Jenkins,
I'd like you to reexamine a change. Please visit
http://gerrit.cloudera.org:8080/23224
to look at the new patch set (#10).
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
---
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(-)
git pull ssh://gerrit.cloudera.org:29418/kudu refs/changes/24/23224/10
--
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: newpatchset
Gerrit-Change-Id: I3981665c78f478e89d0300f3a2fc5d68b73b8762
Gerrit-Change-Number: 23224
Gerrit-PatchSet: 10
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]>
