You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2022/09/01 01:48:55 UTC
[flink] 02/02: [FLINK-28974][sql-gateway]Add doc for the API and Option of sql gateway rest endpoint
This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
commit 55902053a4cf6bf125f7d94c0cf397eaf915479b
Author: Wencong Liu <li...@163.com>
AuthorDate: Tue Aug 30 11:40:30 2022 +0800
[FLINK-28974][sql-gateway]Add doc for the API and Option of sql gateway rest endpoint
This closes #20622
---
.../shortcodes/generated/rest_v1_sql_gateway.html | 783 +++++++++++++++++++++
.../generated/sql_gateway_rest_configuration.html | 36 +
docs/static/generated/rest_v1_sql_gateway.yml | 502 +++++++++++++
flink-docs/pom.xml | 25 +-
.../configuration/ConfigOptionsDocGenerator.java | 2 +
.../flink/docs/rest/OpenApiSpecGenerator.java | 34 +-
.../flink/docs/rest/RestAPIDocGenerator.java | 30 +-
.../docs/rest/RuntimeOpenApiSpecGenerator.java | 61 ++
.../docs/rest/RuntimeRestAPIDocGenerator.java | 85 +++
.../docs/rest/SqlGatewayOpenApiSpecGenerator.java | 61 ++
.../docs/rest/SqlGatewayRestAPIDocGenerator.java | 85 +++
.../header/operation/CancelOperationHeaders.java | 5 +
.../header/operation/CloseOperationHeaders.java | 5 +
.../operation/GetOperationStatusHeaders.java | 5 +
.../rest/header/session/CloseSessionHeaders.java | 5 +
.../header/session/GetSessionConfigHeaders.java | 5 +
.../rest/header/session/OpenSessionHeaders.java | 5 +
.../session/TriggerSessionHeartbeatHeaders.java | 5 +
.../header/statement/ExecuteStatementHeaders.java | 5 +
.../rest/header/statement/FetchResultsHeaders.java | 5 +
.../rest/header/util/GetApiVersionHeaders.java | 5 +
.../gateway/rest/header/util/GetInfoHeaders.java | 5 +
22 files changed, 1700 insertions(+), 59 deletions(-)
diff --git a/docs/layouts/shortcodes/generated/rest_v1_sql_gateway.html b/docs/layouts/shortcodes/generated/rest_v1_sql_gateway.html
new file mode 100644
index 00000000000..cc01710be3b
--- /dev/null
+++ b/docs/layouts/shortcodes/generated/rest_v1_sql_gateway.html
@@ -0,0 +1,783 @@
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/api_versions</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>GET</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Get the current available versions for the Rest Endpoint. The client can choose one of the return version as the protocol for later communicate.</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetApiVersionResponseBody",
+ "properties" : {
+ "versions" : {
+ "type" : "array",
+ "items" : {
+ "type" : "string"
+ }
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/info</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>GET</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Get meta data for this cluster.</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:util:GetInfoResponseBody",
+ "properties" : {
+ "productName" : {
+ "type" : "string"
+ },
+ "version" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>POST</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Opens a new session with specific properties. Specific properties can be given for current session which will override the default properties of gateway.</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionRequestBody",
+ "properties" : {
+ "properties" : {
+ "type" : "object",
+ "additionalProperties" : {
+ "type" : "string"
+ }
+ },
+ "sessionName" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:OpenSessionResponseBody",
+ "properties" : {
+ "sessionHandle" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>DELETE</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Closes the specific session.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:CloseSessionResponseBody",
+ "properties" : {
+ "status" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>GET</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Get the session configuration.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:session:GetSessionConfigResponseBody",
+ "properties" : {
+ "properties" : {
+ "type" : "object",
+ "additionalProperties" : {
+ "type" : "string"
+ }
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/heartbeat</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>POST</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Trigger heartbeat to tell the server that the client is active, and to keep the session alive as long as configured timeout value.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/operations/:operation_handle/cancel</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>POST</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Cancel the operation.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+<li><code>operation_handle</code> - The OperationHandle that identifies a operation.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
+ "properties" : {
+ "status" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/operations/:operation_handle/close</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>DELETE</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Close the operation.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+<li><code>operation_handle</code> - The OperationHandle that identifies a operation.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
+ "properties" : {
+ "status" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/operations/:operation_handle/result/:token</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>GET</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Fetch results of Operation.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+<li><code>operation_handle</code> - The OperationHandle that identifies a operation.</li>
+<li><code>token</code> - The OperationHandle that identifies a operation.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:FetchResultsResponseBody",
+ "properties" : {
+ "nextResultUri" : {
+ "type" : "string"
+ },
+ "resultType" : {
+ "type" : "string"
+ },
+ "results" : {
+ "type" : "any"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/operations/:operation_handle/status</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>GET</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Get the status of operation.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+<li><code>operation_handle</code> - The OperationHandle that identifies a operation.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:operation:OperationStatusResponseBody",
+ "properties" : {
+ "status" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<table class="rest-api table table-bordered">
+ <tbody>
+ <tr>
+ <td class="text-left" colspan="2"><h5><strong>/sessions/:session_handle/statements</strong></h5></td>
+ </tr>
+ <tr>
+ <td class="text-left" style="width: 20%">Verb: <code>POST</code></td>
+ <td class="text-left">Response code: <code>200 OK</code></td>
+ </tr>
+ <tr>
+ <td colspan="2">Execute a statement.</td>
+ </tr>
+ <tr>
+ <td colspan="2">Path parameters</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <ul>
+<li><code>session_handle</code> - The SessionHandle that identifies a session.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Request</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementRequestBody",
+ "properties" : {
+ "executionConfig" : {
+ "type" : "object",
+ "additionalProperties" : {
+ "type" : "string"
+ }
+ },
+ "executionTimeout" : {
+ "type" : "integer"
+ },
+ "statement" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <div class="book-expand">
+ <label>
+ <div class="book-expand-head flex justify-between">
+ <span>Response</span>
+ <span>▾</span>
+ </div>
+ <input type="checkbox" class="hidden">
+ <div class="book-expand-content markdown-inner">
+ <pre>
+ <code>
+{
+ "type" : "object",
+ "id" : "urn:jsonschema:org:apache:flink:table:gateway:rest:message:statement:ExecuteStatementResponseBody",
+ "properties" : {
+ "operationHandle" : {
+ "type" : "string"
+ }
+ }
+} </code>
+ </pre>
+ </div>
+ </label>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+</table>
diff --git a/docs/layouts/shortcodes/generated/sql_gateway_rest_configuration.html b/docs/layouts/shortcodes/generated/sql_gateway_rest_configuration.html
new file mode 100644
index 00000000000..96808c286f5
--- /dev/null
+++ b/docs/layouts/shortcodes/generated/sql_gateway_rest_configuration.html
@@ -0,0 +1,36 @@
+<table class="configuration table table-bordered">
+ <thead>
+ <tr>
+ <th class="text-left" style="width: 20%">Key</th>
+ <th class="text-left" style="width: 15%">Default</th>
+ <th class="text-left" style="width: 10%">Type</th>
+ <th class="text-left" style="width: 55%">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><h5>address</h5></td>
+ <td style="word-wrap: break-word;">(none)</td>
+ <td>String</td>
+ <td>The address that should be used by clients to connect to the sql gateway server.</td>
+ </tr>
+ <tr>
+ <td><h5>bind-address</h5></td>
+ <td style="word-wrap: break-word;">(none)</td>
+ <td>String</td>
+ <td>The address that the sql gateway server binds itself.</td>
+ </tr>
+ <tr>
+ <td><h5>bind-port</h5></td>
+ <td style="word-wrap: break-word;">"8083"</td>
+ <td>String</td>
+ <td>The port that the sql gateway server binds itself. Accepts a list of ports (“50100,50101”), ranges (“50100-50200”) or a combination of both. It is recommended to set a range of ports to avoid collisions when multiple sql gateway servers are running on the same machine.</td>
+ </tr>
+ <tr>
+ <td><h5>port</h5></td>
+ <td style="word-wrap: break-word;">8083</td>
+ <td>Integer</td>
+ <td>The port that the client connects to. If bind-port has not been specified, then the sql gateway server will bind to this port.</td>
+ </tr>
+ </tbody>
+</table>
diff --git a/docs/static/generated/rest_v1_sql_gateway.yml b/docs/static/generated/rest_v1_sql_gateway.yml
new file mode 100644
index 00000000000..209e83b2a2d
--- /dev/null
+++ b/docs/static/generated/rest_v1_sql_gateway.yml
@@ -0,0 +1,502 @@
+openapi: 3.0.1
+info:
+ title: Flink JobManager REST API
+ contact:
+ email: user@flink.apache.org
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: v1/1.16-SNAPSHOT
+paths:
+ /api_versions:
+ get:
+ description: Get the current available versions for the Rest Endpoint. The client
+ can choose one of the return version as the protocol for later communicate.
+ operationId: getApiVersion
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GetApiVersionResponseBody'
+ /info:
+ get:
+ description: Get meta data for this cluster.
+ operationId: getInfo
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GetInfoResponseBody'
+ /sessions:
+ post:
+ description: Opens a new session with specific properties. Specific properties
+ can be given for current session which will override the default properties
+ of gateway.
+ operationId: openSession
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OpenSessionRequestBody'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OpenSessionResponseBody'
+ /sessions/{session_handle}:
+ get:
+ description: Get the session configuration.
+ operationId: getSessionConfig
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GetSessionConfigResponseBody'
+ delete:
+ description: Closes the specific session.
+ operationId: closeSession
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CloseSessionResponseBody'
+ /sessions/{session_handle}/heartbeat:
+ post:
+ description: "Trigger heartbeat to tell the server that the client is active,\
+ \ and to keep the session alive as long as configured timeout value."
+ operationId: triggerSession
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ /sessions/{session_handle}/operations/{operation_handle}/cancel:
+ post:
+ description: Cancel the operation.
+ operationId: cancelOperation
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ - name: operation_handle
+ in: path
+ description: The OperationHandle that identifies a operation.
+ required: true
+ schema:
+ $ref: '#/components/schemas/OperationHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OperationStatusResponseBody'
+ /sessions/{session_handle}/operations/{operation_handle}/close:
+ delete:
+ description: Close the operation.
+ operationId: closeOperation
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ - name: operation_handle
+ in: path
+ description: The OperationHandle that identifies a operation.
+ required: true
+ schema:
+ $ref: '#/components/schemas/OperationHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OperationStatusResponseBody'
+ /sessions/{session_handle}/operations/{operation_handle}/result/{token}:
+ get:
+ description: Fetch results of Operation.
+ operationId: fetchResults
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ - name: operation_handle
+ in: path
+ description: The OperationHandle that identifies a operation.
+ required: true
+ schema:
+ $ref: '#/components/schemas/OperationHandle'
+ - name: token
+ in: path
+ description: The OperationHandle that identifies a operation.
+ required: true
+ schema:
+ type: integer
+ format: int64
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/FetchResultsResponseBody'
+ /sessions/{session_handle}/operations/{operation_handle}/status:
+ get:
+ description: Get the status of operation.
+ operationId: getOperationStatus
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ - name: operation_handle
+ in: path
+ description: The OperationHandle that identifies a operation.
+ required: true
+ schema:
+ $ref: '#/components/schemas/OperationHandle'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OperationStatusResponseBody'
+ /sessions/{session_handle}/statements:
+ post:
+ description: Execute a statement.
+ operationId: executeStatement
+ parameters:
+ - name: session_handle
+ in: path
+ description: The SessionHandle that identifies a session.
+ required: true
+ schema:
+ $ref: '#/components/schemas/SessionHandle'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ExecuteStatementRequestBody'
+ responses:
+ "200":
+ description: The request was successful.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ExecuteStatementResponseBody'
+components:
+ schemas:
+ CloseSessionResponseBody:
+ type: object
+ properties:
+ status:
+ type: string
+ WatermarkSpec:
+ type: object
+ properties:
+ rowtimeAttribute:
+ type: string
+ watermarkExpression:
+ $ref: '#/components/schemas/ResolvedExpression'
+ GetInfoResponseBody:
+ type: object
+ properties:
+ productName:
+ type: string
+ version:
+ type: string
+ JobVertexID:
+ pattern: "[0-9a-f]{32}"
+ type: string
+ ResolvedExpression:
+ type: object
+ properties:
+ outputDataType:
+ $ref: '#/components/schemas/DataType'
+ resolvedChildren:
+ type: array
+ items:
+ $ref: '#/components/schemas/ResolvedExpression'
+ children:
+ type: array
+ items:
+ $ref: '#/components/schemas/Expression'
+ LogicalType:
+ type: object
+ properties:
+ typeRoot:
+ $ref: '#/components/schemas/LogicalTypeRoot'
+ nullable:
+ type: boolean
+ children:
+ type: array
+ items:
+ $ref: '#/components/schemas/LogicalType'
+ UniqueConstraint:
+ type: object
+ properties:
+ name:
+ type: string
+ enforced:
+ type: boolean
+ columns:
+ type: array
+ items:
+ type: string
+ type:
+ $ref: '#/components/schemas/ConstraintType'
+ ExecuteStatementRequestBody:
+ type: object
+ properties:
+ statement:
+ type: string
+ executionTimeout:
+ type: integer
+ format: int64
+ executionConfig:
+ type: object
+ additionalProperties:
+ type: string
+ LogicalTypeRoot:
+ type: string
+ enum:
+ - CHAR
+ - VARCHAR
+ - BOOLEAN
+ - BINARY
+ - VARBINARY
+ - DECIMAL
+ - TINYINT
+ - SMALLINT
+ - INTEGER
+ - BIGINT
+ - FLOAT
+ - DOUBLE
+ - DATE
+ - TIME_WITHOUT_TIME_ZONE
+ - TIMESTAMP_WITHOUT_TIME_ZONE
+ - TIMESTAMP_WITH_TIME_ZONE
+ - TIMESTAMP_WITH_LOCAL_TIME_ZONE
+ - INTERVAL_YEAR_MONTH
+ - INTERVAL_DAY_TIME
+ - ARRAY
+ - MULTISET
+ - MAP
+ - ROW
+ - DISTINCT_TYPE
+ - STRUCTURED_TYPE
+ - "NULL"
+ - RAW
+ - SYMBOL
+ - UNRESOLVED
+ OperationHandle:
+ type: object
+ properties:
+ identifier:
+ type: string
+ format: uuid
+ ExecuteStatementResponseBody:
+ type: object
+ properties:
+ operationHandle:
+ type: string
+ FetchResultsResponseBody:
+ type: object
+ properties:
+ results:
+ $ref: '#/components/schemas/ResultSet'
+ resultType:
+ type: string
+ nextResultUri:
+ type: string
+ RowData:
+ type: object
+ properties:
+ rowKind:
+ $ref: '#/components/schemas/RowKind'
+ arity:
+ type: integer
+ format: int32
+ Column:
+ type: object
+ properties:
+ name:
+ type: string
+ dataType:
+ $ref: '#/components/schemas/DataType'
+ comment:
+ type: string
+ physical:
+ type: boolean
+ persisted:
+ type: boolean
+ TriggerId:
+ pattern: "[0-9a-f]{32}"
+ type: string
+ ResourceID:
+ pattern: "[0-9a-f]{32}"
+ type: string
+ OpenSessionRequestBody:
+ type: object
+ properties:
+ sessionName:
+ type: string
+ properties:
+ type: object
+ additionalProperties:
+ type: string
+ ResultSet:
+ type: object
+ properties:
+ resultType:
+ $ref: '#/components/schemas/ResultType'
+ nextToken:
+ type: integer
+ format: int64
+ resultSchema:
+ $ref: '#/components/schemas/ResolvedSchema'
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/RowData'
+ DataType:
+ type: object
+ properties:
+ logicalType:
+ $ref: '#/components/schemas/LogicalType'
+ children:
+ type: array
+ items:
+ $ref: '#/components/schemas/DataType'
+ ResolvedSchema:
+ type: object
+ properties:
+ columns:
+ type: array
+ items:
+ $ref: '#/components/schemas/Column'
+ watermarkSpecs:
+ type: array
+ items:
+ $ref: '#/components/schemas/WatermarkSpec'
+ primaryKey:
+ $ref: '#/components/schemas/UniqueConstraint'
+ columnNames:
+ type: array
+ items:
+ type: string
+ primaryKeyIndexes:
+ type: array
+ items:
+ type: integer
+ format: int32
+ columnCount:
+ type: integer
+ format: int32
+ columnDataTypes:
+ type: array
+ items:
+ $ref: '#/components/schemas/DataType'
+ GetSessionConfigResponseBody:
+ type: object
+ properties:
+ properties:
+ type: object
+ additionalProperties:
+ type: string
+ SerializedThrowable:
+ type: object
+ properties:
+ serialized-throwable:
+ type: string
+ format: binary
+ GetApiVersionResponseBody:
+ type: object
+ properties:
+ versions:
+ type: array
+ items:
+ type: string
+ OperationStatusResponseBody:
+ type: object
+ properties:
+ status:
+ type: string
+ SessionHandle:
+ type: object
+ properties:
+ identifier:
+ type: string
+ format: uuid
+ ResultType:
+ type: string
+ enum:
+ - NOT_READY
+ - PAYLOAD
+ - EOS
+ Expression:
+ type: object
+ RowKind:
+ type: string
+ enum:
+ - INSERT
+ - UPDATE_BEFORE
+ - UPDATE_AFTER
+ - DELETE
+ OpenSessionResponseBody:
+ type: object
+ properties:
+ sessionHandle:
+ type: string
+ ConstraintType:
+ type: string
+ enum:
+ - PRIMARY_KEY
+ - UNIQUE_KEY
+ IntermediateDataSetID:
+ pattern: "[0-9a-f]{32}"
+ type: string
+ JobID:
+ pattern: "[0-9a-f]{32}"
+ type: string
diff --git a/flink-docs/pom.xml b/flink-docs/pom.xml
index d9a17f6c301..647f55271be 100644
--- a/flink-docs/pom.xml
+++ b/flink-docs/pom.xml
@@ -173,6 +173,19 @@ under the License.
<version>${project.version}</version>
</dependency>
+ <dependency>
+ <groupId>org.apache.flink</groupId>
+ <artifactId>flink-sql-gateway</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.flink</groupId>
+ <artifactId>flink-sql-gateway</artifactId>
+ <version>${project.version}</version>
+ <type>test-jar</type>
+ </dependency>
+
<dependency>
<!-- Used for parsing HTML -->
<groupId>org.jsoup</groupId>
@@ -252,11 +265,19 @@ under the License.
<configuration>
<target>
<mkdir dir="${rootDir}/${generated.docs.dir}"/>
- <java classname="org.apache.flink.docs.rest.RestAPIDocGenerator" fork="true" failonerror="true">
+ <java classname="org.apache.flink.docs.rest.RuntimeRestAPIDocGenerator" fork="true" failonerror="true">
+ <classpath refid="maven.compile.classpath"/>
+ <arg value="${rootDir}/${generated.docs.dir}/"/>
+ </java>
+ <java classname="org.apache.flink.docs.rest.RuntimeOpenApiSpecGenerator" fork="true" failonerror="true">
+ <classpath refid="maven.compile.classpath"/>
+ <arg value="${rootDir}/${generated.static.dir}/"/>
+ </java>
+ <java classname="org.apache.flink.docs.rest.SqlGatewayRestAPIDocGenerator" fork="true" failonerror="true">
<classpath refid="maven.compile.classpath"/>
<arg value="${rootDir}/${generated.docs.dir}/"/>
</java>
- <java classname="org.apache.flink.docs.rest.OpenApiSpecGenerator" fork="true" failonerror="true">
+ <java classname="org.apache.flink.docs.rest.SqlGatewayOpenApiSpecGenerator" fork="true" failonerror="true">
<classpath refid="maven.compile.classpath"/>
<arg value="${rootDir}/${generated.static.dir}/"/>
</java>
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
index 5b557cd105f..ec978e422cc 100644
--- a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
+++ b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
@@ -114,6 +114,8 @@ public class ConfigOptionsDocGenerator {
"flink-libraries/flink-cep", "org.apache.flink.cep.configuration"),
new OptionsClassLocation(
"flink-dstl/flink-dstl-dfs", "org.apache.flink.changelog.fs"),
+ new OptionsClassLocation(
+ "flink-table/flink-sql-gateway", "org.apache.flink.table.gateway.rest.util")
};
static final Set<String> EXCLUSIONS =
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/OpenApiSpecGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/OpenApiSpecGenerator.java
index fe17e807f8f..931ef8d6a3c 100644
--- a/flink-docs/src/main/java/org/apache/flink/docs/rest/OpenApiSpecGenerator.java
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/OpenApiSpecGenerator.java
@@ -37,12 +37,10 @@ import org.apache.flink.runtime.rest.messages.MessageQueryParameter;
import org.apache.flink.runtime.rest.messages.TriggerId;
import org.apache.flink.runtime.rest.messages.job.JobSubmitHeaders;
import org.apache.flink.runtime.rest.messages.json.SerializedThrowableSerializer;
-import org.apache.flink.runtime.rest.util.DocumentingDispatcherRestEndpoint;
import org.apache.flink.runtime.rest.util.DocumentingRestEndpoint;
-import org.apache.flink.runtime.rest.versioning.RuntimeRestAPIVersion;
+import org.apache.flink.runtime.rest.versioning.RestAPIVersion;
import org.apache.flink.runtime.util.EnvironmentInformation;
import org.apache.flink.runtime.webmonitor.handlers.JarUploadHeaders;
-import org.apache.flink.util.ConfigurationException;
import org.apache.flink.util.SerializedThrowable;
import org.apache.flink.util.jackson.JacksonMapperFactory;
@@ -77,7 +75,6 @@ import java.lang.reflect.Type;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
-import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
@@ -107,32 +104,9 @@ public class OpenApiSpecGenerator {
new ModelConverterContextImpl(Collections.singletonList(new ModelResolver(mapper)));
}
- /**
- * Generates the REST API OpenAPI spec.
- *
- * @param args args[0] contains the directory into which the generated files are placed
- * @throws IOException if any file operation failed
- */
- public static void main(String[] args) throws IOException, ConfigurationException {
- String outputDirectory = args[0];
-
- for (final RuntimeRestAPIVersion apiVersion : RuntimeRestAPIVersion.values()) {
- if (apiVersion == RuntimeRestAPIVersion.V0) {
- // this version exists only for testing purposes
- continue;
- }
- createDocumentationFile(
- new DocumentingDispatcherRestEndpoint(),
- apiVersion,
- Paths.get(
- outputDirectory,
- "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.yml"));
- }
- }
-
@VisibleForTesting
static void createDocumentationFile(
- DocumentingRestEndpoint restEndpoint, RuntimeRestAPIVersion apiVersion, Path outputFile)
+ DocumentingRestEndpoint restEndpoint, RestAPIVersion apiVersion, Path outputFile)
throws IOException {
final OpenAPI openApi = new OpenAPI();
@@ -169,7 +143,7 @@ public class OpenApiSpecGenerator {
return spec.getClass().getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
- private static void setInfo(final OpenAPI openApi, final RuntimeRestAPIVersion apiVersion) {
+ private static void setInfo(final OpenAPI openApi, final RestAPIVersion apiVersion) {
openApi.info(
new Info()
.title("Flink JobManager REST API")
@@ -453,6 +427,8 @@ public class OpenApiSpecGenerator {
return PathItem.HttpMethod.DELETE;
case PATCH:
return PathItem.HttpMethod.PATCH;
+ case PUT:
+ return PathItem.HttpMethod.PUT;
}
throw new IllegalArgumentException("not supported");
}
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/RestAPIDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/RestAPIDocGenerator.java
index a21ec24cc3e..d3de725e682 100644
--- a/flink-docs/src/main/java/org/apache/flink/docs/rest/RestAPIDocGenerator.java
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/RestAPIDocGenerator.java
@@ -28,10 +28,8 @@ import org.apache.flink.runtime.rest.messages.EmptyResponseBody;
import org.apache.flink.runtime.rest.messages.MessageHeaders;
import org.apache.flink.runtime.rest.messages.MessagePathParameter;
import org.apache.flink.runtime.rest.messages.MessageQueryParameter;
-import org.apache.flink.runtime.rest.util.DocumentingDispatcherRestEndpoint;
import org.apache.flink.runtime.rest.util.DocumentingRestEndpoint;
-import org.apache.flink.runtime.rest.versioning.RuntimeRestAPIVersion;
-import org.apache.flink.util.ConfigurationException;
+import org.apache.flink.runtime.rest.versioning.RestAPIVersion;
import org.apache.flink.util.jackson.JacksonMapperFactory;
import org.apache.flink.shaded.jackson2.com.fasterxml.jackson.core.JsonProcessingException;
@@ -52,7 +50,6 @@ import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
-import java.nio.file.Paths;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
@@ -106,32 +103,9 @@ public class RestAPIDocGenerator {
schemaGen = new JsonSchemaGenerator(mapper);
}
- /**
- * Generates the REST API documentation.
- *
- * @param args args[0] contains the directory into which the generated files are placed
- * @throws IOException if any file operation failed
- */
- public static void main(String[] args) throws IOException, ConfigurationException {
- String outputDirectory = args[0];
-
- for (final RuntimeRestAPIVersion apiVersion : RuntimeRestAPIVersion.values()) {
- if (apiVersion == RuntimeRestAPIVersion.V0) {
- // this version exists only for testing purposes
- continue;
- }
- createHtmlFile(
- new DocumentingDispatcherRestEndpoint(),
- apiVersion,
- Paths.get(
- outputDirectory,
- "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.html"));
- }
- }
-
@VisibleForTesting
static void createHtmlFile(
- DocumentingRestEndpoint restEndpoint, RuntimeRestAPIVersion apiVersion, Path outputFile)
+ DocumentingRestEndpoint restEndpoint, RestAPIVersion apiVersion, Path outputFile)
throws IOException {
StringBuilder html = new StringBuilder();
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeOpenApiSpecGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeOpenApiSpecGenerator.java
new file mode 100644
index 00000000000..9c2c8b34c22
--- /dev/null
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeOpenApiSpecGenerator.java
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.docs.rest;
+
+import org.apache.flink.runtime.rest.RestServerEndpoint;
+import org.apache.flink.runtime.rest.util.DocumentingDispatcherRestEndpoint;
+import org.apache.flink.runtime.rest.versioning.RuntimeRestAPIVersion;
+import org.apache.flink.util.ConfigurationException;
+
+import java.io.IOException;
+import java.nio.file.Paths;
+
+import static org.apache.flink.docs.rest.OpenApiSpecGenerator.createDocumentationFile;
+
+/**
+ * OpenAPI spec generator for the Runtime Rest API.
+ *
+ * <p>One OpenAPI yml file is generated for each {@link RestServerEndpoint} implementation that can
+ * be embedded into .md files using {@code {% include ${generated.docs.dir}/file.yml %}}.
+ */
+public class RuntimeOpenApiSpecGenerator {
+
+ /**
+ * Generates the Runtime REST API OpenAPI spec.
+ *
+ * @param args args[0] contains the directory into which the generated files are placed
+ * @throws IOException if any file operation failed
+ */
+ public static void main(String[] args) throws IOException, ConfigurationException {
+ String outputDirectory = args[0];
+
+ for (final RuntimeRestAPIVersion apiVersion : RuntimeRestAPIVersion.values()) {
+ if (apiVersion == RuntimeRestAPIVersion.V0) {
+ // this version exists only for testing purposes
+ continue;
+ }
+ createDocumentationFile(
+ new DocumentingDispatcherRestEndpoint(),
+ apiVersion,
+ Paths.get(
+ outputDirectory,
+ "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.yml"));
+ }
+ }
+}
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeRestAPIDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeRestAPIDocGenerator.java
new file mode 100644
index 00000000000..b13f6d68dec
--- /dev/null
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/RuntimeRestAPIDocGenerator.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.docs.rest;
+
+import org.apache.flink.runtime.rest.RestServerEndpoint;
+import org.apache.flink.runtime.rest.util.DocumentingDispatcherRestEndpoint;
+import org.apache.flink.runtime.rest.versioning.RuntimeRestAPIVersion;
+import org.apache.flink.util.ConfigurationException;
+
+import java.io.IOException;
+import java.nio.file.Paths;
+
+import static org.apache.flink.docs.rest.RestAPIDocGenerator.createHtmlFile;
+
+/**
+ * Generator for the Runtime Rest API documentation.
+ *
+ * <p>One HTML file is generated for each {@link RestServerEndpoint} implementation that can be
+ * embedded into .md files using {@code {% include ${generated.docs.dir}/file.html %}}. Each file
+ * contains a series of HTML tables, one for each REST call.
+ *
+ * <p>The generated table for each REST call looks like this:
+ *
+ * <pre>
+ * ----------------------------------------------------------
+ * | URL |
+ * ----------------------------------------------------------
+ * | Verb: verb (GET|POST|...) | Response code: responseCode|
+ * ----------------------------------------------------------
+ * | Path parameters (if any are defined) |
+ * ----------------------------------------------------------
+ * | - parameterName: description |
+ * | ... |
+ * ----------------------------------------------------------
+ * | Query parameters (if any are defined) |
+ * ----------------------------------------------------------
+ * | - parameterName (requisiteness): description |
+ * | ... |
+ * ----------------------------------------------------------
+ * | Request json schema (a collapsible "Request" button) |
+ * ----------------------------------------------------------
+ * | Response json schema (a collapsible "Response" button) |
+ * ----------------------------------------------------------
+ * </pre>
+ */
+public class RuntimeRestAPIDocGenerator {
+ /**
+ * Generates the Runtime REST API documentation.
+ *
+ * @param args args[0] contains the directory into which the generated files are placed
+ * @throws IOException if any file operation failed
+ */
+ public static void main(String[] args) throws IOException, ConfigurationException {
+ String outputDirectory = args[0];
+
+ for (final RuntimeRestAPIVersion apiVersion : RuntimeRestAPIVersion.values()) {
+ if (apiVersion == RuntimeRestAPIVersion.V0) {
+ // this version exists only for testing purposes
+ continue;
+ }
+ createHtmlFile(
+ new DocumentingDispatcherRestEndpoint(),
+ apiVersion,
+ Paths.get(
+ outputDirectory,
+ "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.html"));
+ }
+ }
+}
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayOpenApiSpecGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayOpenApiSpecGenerator.java
new file mode 100644
index 00000000000..87015c6f87e
--- /dev/null
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayOpenApiSpecGenerator.java
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.docs.rest;
+
+import org.apache.flink.runtime.rest.RestServerEndpoint;
+import org.apache.flink.table.gateway.rest.util.DocumentingSqlGatewayRestEndpoint;
+import org.apache.flink.table.gateway.rest.util.SqlGatewayRestAPIVersion;
+import org.apache.flink.util.ConfigurationException;
+
+import java.io.IOException;
+import java.nio.file.Paths;
+
+import static org.apache.flink.docs.rest.OpenApiSpecGenerator.createDocumentationFile;
+
+/**
+ * OpenAPI spec generator for the Sql Gateway Rest API.
+ *
+ * <p>One OpenAPI yml file is generated for each {@link RestServerEndpoint} implementation that can
+ * be embedded into .md files using {@code {% include ${generated.docs.dir}/file.yml %}}.
+ */
+public class SqlGatewayOpenApiSpecGenerator {
+
+ /**
+ * Generates the Sql Gateway REST API OpenAPI spec.
+ *
+ * @param args args[0] contains the directory into which the generated files are placed
+ * @throws IOException if any file operation failed
+ */
+ public static void main(String[] args) throws IOException, ConfigurationException {
+ String outputDirectory = args[0];
+
+ for (final SqlGatewayRestAPIVersion apiVersion : SqlGatewayRestAPIVersion.values()) {
+ if (apiVersion == SqlGatewayRestAPIVersion.V0) {
+ // this version exists only for testing purposes
+ continue;
+ }
+ createDocumentationFile(
+ new DocumentingSqlGatewayRestEndpoint(),
+ apiVersion,
+ Paths.get(
+ outputDirectory,
+ "rest_" + apiVersion.getURLVersionPrefix() + "_sql_gateway.yml"));
+ }
+ }
+}
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayRestAPIDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayRestAPIDocGenerator.java
new file mode 100644
index 00000000000..c47e48cd48b
--- /dev/null
+++ b/flink-docs/src/main/java/org/apache/flink/docs/rest/SqlGatewayRestAPIDocGenerator.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.docs.rest;
+
+import org.apache.flink.runtime.rest.RestServerEndpoint;
+import org.apache.flink.table.gateway.rest.util.DocumentingSqlGatewayRestEndpoint;
+import org.apache.flink.table.gateway.rest.util.SqlGatewayRestAPIVersion;
+import org.apache.flink.util.ConfigurationException;
+
+import java.io.IOException;
+import java.nio.file.Paths;
+
+import static org.apache.flink.docs.rest.RestAPIDocGenerator.createHtmlFile;
+
+/**
+ * Generator for the Sql Gateway Rest API documentation.
+ *
+ * <p>One HTML file is generated for each {@link RestServerEndpoint} implementation that can be
+ * embedded into .md files using {@code {% include ${generated.docs.dir}/file.html %}}. Each file
+ * contains a series of HTML tables, one for each REST call.
+ *
+ * <p>The generated table for each REST call looks like this:
+ *
+ * <pre>
+ * ----------------------------------------------------------
+ * | URL |
+ * ----------------------------------------------------------
+ * | Verb: verb (GET|POST|...) | Response code: responseCode|
+ * ----------------------------------------------------------
+ * | Path parameters (if any are defined) |
+ * ----------------------------------------------------------
+ * | - parameterName: description |
+ * | ... |
+ * ----------------------------------------------------------
+ * | Query parameters (if any are defined) |
+ * ----------------------------------------------------------
+ * | - parameterName (requisiteness): description |
+ * | ... |
+ * ----------------------------------------------------------
+ * | Request json schema (a collapsible "Request" button) |
+ * ----------------------------------------------------------
+ * | Response json schema (a collapsible "Response" button) |
+ * ----------------------------------------------------------
+ * </pre>
+ */
+public class SqlGatewayRestAPIDocGenerator {
+
+ /**
+ * Generates the Sql Gateway REST API documentation.
+ *
+ * @param args args[0] contains the directory into which the generated files are placed
+ * @throws IOException if any file operation failed
+ */
+ public static void main(String[] args) throws IOException, ConfigurationException {
+ String outputDirectory = args[0];
+ for (final SqlGatewayRestAPIVersion apiVersion : SqlGatewayRestAPIVersion.values()) {
+ if (apiVersion == SqlGatewayRestAPIVersion.V0) {
+ // this version exists only for testing purposes
+ continue;
+ }
+ createHtmlFile(
+ new DocumentingSqlGatewayRestEndpoint(),
+ apiVersion,
+ Paths.get(
+ outputDirectory,
+ "rest_" + apiVersion.getURLVersionPrefix() + "_sql_gateway.html"));
+ }
+ }
+}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CancelOperationHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CancelOperationHeaders.java
index ab716df6fcf..e25a31c6fbe 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CancelOperationHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CancelOperationHeaders.java
@@ -52,4 +52,9 @@ public class CancelOperationHeaders extends AbstactOperationHeaders {
public static CancelOperationHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "cancelOperation";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CloseOperationHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CloseOperationHeaders.java
index 3d634f0eee8..1b9ae4ea4ec 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CloseOperationHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/CloseOperationHeaders.java
@@ -52,4 +52,9 @@ public class CloseOperationHeaders extends AbstactOperationHeaders {
public static CloseOperationHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "closeOperation";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/GetOperationStatusHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/GetOperationStatusHeaders.java
index 0d8f5f68260..f05d1538667 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/GetOperationStatusHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/operation/GetOperationStatusHeaders.java
@@ -52,4 +52,9 @@ public class GetOperationStatusHeaders extends AbstactOperationHeaders {
public static GetOperationStatusHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "getOperationStatus";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/CloseSessionHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/CloseSessionHeaders.java
index 2d12a6b9358..62ee5a3e339 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/CloseSessionHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/CloseSessionHeaders.java
@@ -76,4 +76,9 @@ public class CloseSessionHeaders
public static CloseSessionHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "closeSession";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/GetSessionConfigHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/GetSessionConfigHeaders.java
index 04df823da50..701e3372057 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/GetSessionConfigHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/GetSessionConfigHeaders.java
@@ -76,4 +76,9 @@ public class GetSessionConfigHeaders
public static GetSessionConfigHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "getSessionConfig";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/OpenSessionHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/OpenSessionHeaders.java
index 6759ce263fb..1161d583965 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/OpenSessionHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/OpenSessionHeaders.java
@@ -75,4 +75,9 @@ public class OpenSessionHeaders
public static OpenSessionHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "openSession";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/TriggerSessionHeartbeatHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/TriggerSessionHeartbeatHeaders.java
index 1b541ab62e6..93d0757f99d 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/TriggerSessionHeartbeatHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/session/TriggerSessionHeartbeatHeaders.java
@@ -76,4 +76,9 @@ public class TriggerSessionHeartbeatHeaders
public static TriggerSessionHeartbeatHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "triggerSession";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/ExecuteStatementHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/ExecuteStatementHeaders.java
index 17f84fa6686..fb30d3fb83a 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/ExecuteStatementHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/ExecuteStatementHeaders.java
@@ -77,4 +77,9 @@ public class ExecuteStatementHeaders
public static ExecuteStatementHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "executeStatement";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/FetchResultsHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/FetchResultsHeaders.java
index da6c894bd5a..274b24ff129 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/FetchResultsHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/statement/FetchResultsHeaders.java
@@ -97,4 +97,9 @@ public class FetchResultsHeaders
public FetchResultsTokenParameters getUnresolvedMessageParameters() {
return new FetchResultsTokenParameters();
}
+
+ @Override
+ public String operationId() {
+ return "fetchResults";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetApiVersionHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetApiVersionHeaders.java
index e8a6071d525..238db0f3608 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetApiVersionHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetApiVersionHeaders.java
@@ -74,4 +74,9 @@ public class GetApiVersionHeaders
public static GetApiVersionHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "getApiVersion";
+ }
}
diff --git a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetInfoHeaders.java b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetInfoHeaders.java
index 4935ed1faeb..2ff68bc11fc 100644
--- a/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetInfoHeaders.java
+++ b/flink-table/flink-sql-gateway/src/main/java/org/apache/flink/table/gateway/rest/header/util/GetInfoHeaders.java
@@ -74,4 +74,9 @@ public class GetInfoHeaders
public static GetInfoHeaders getInstance() {
return INSTANCE;
}
+
+ @Override
+ public String operationId() {
+ return "getInfo";
+ }
}