Merge pull request #1452 from The-K-R-O-K/AndriiSlisarchuk/fix-openap…

…i-for-documentation Andrii slisarchuk/fix openapi for documentation
onflow · Apr 26, 2024 · 3b24cdb · 3b24cdb
2 parents 1a90022 + 5406540
commit 3b24cdb
Show file tree

Hide file tree

Showing 4 changed files with 106 additions and 43 deletions.
diff --git a/openapi/access.yaml b/openapi/access.yaml
@@ -573,7 +573,10 @@ paths:
   /subscribe_events:
     get:
       summary: Subscribe events
-      description: Streaming on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new block as it becomes available.
+      description: |
+        IMPORTANT NOTE: This is a WebSocket connection, so the `ws://` or `wss://` schema should be used to subscribe to this endpoint.
+
+        This endpoint streams on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest block is reached, the stream will remain open, and responses will be sent for each new block as it becomes available.
       tags:
         - Subscribe events
       responses:
@@ -583,14 +586,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SubscribeEvents'
           description: OK
-        '1001':
-          $ref: '#/components/responses/1001CloseGoingAway'
-        '1003':
-          $ref: '#/components/responses/1003CloseUnsupportedData'
-        '1011':
-          $ref: '#/components/responses/1011CloseInternalServerError'
-        '1013':
-          $ref: '#/components/responses/1013CloseTryAgaitLater'
+        '400':
+          $ref: '#/components/responses/400BadRequestWS'
+        '408':
+          $ref: '#/components/responses/408ServerTimeoutWS'
+        '500':
+          $ref: '#/components/responses/500InternalServerErrorWS'
+        '503':
+          $ref: '#/components/responses/503ServiceUnavailableWS'
       parameters:
         - name: start_height
           in: query
@@ -1239,32 +1242,56 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+    408ServerTimeout:
+      description: Server Timeout
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
     500InternalServerError:
       description: Internal Server Error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    1001CloseGoingAway:
-      description: Going Away
+    503ServiceUnavailable:
+      description: Service Unavailable
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    1003CloseUnsupportedData:
-      description: Unsupported Data
+    400BadRequestWS:
+      description: |
+        Bad Request
+      
+        As OpenAPI does not support WebSocket description, the error code (1003) is actually returned in a close message instead of (400).
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    1011CloseInternalServerError:
-      description: Internal Server Error
+    408ServerTimeoutWS:
+      description: |
+        Server Timeout
+        
+        As OpenAPI does not support WebSocket description, this error code (1001) is actually returned in a close message instead of (408).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    500InternalServerErrorWS:
+      description: |
+        Internal Server Error
+        
+        As OpenAPI does not support WebSocket description, this error code (1011) is actually returned in a close message instead of (500).
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    1013CloseTryAgaitLater:
-      description: Try Agait Later
+    503ServiceUnavailableWS:
+      description: |
+        Service Unavailable
+        
+        As OpenAPI does not support WebSocket description, this error code (1013) is actually returned in a close message instead of (503).
       content:
         application/json:
           schema:

diff --git a/openapi/go-client-generated/api/swagger.yaml b/openapi/go-client-generated/api/swagger.yaml
@@ -1005,10 +1005,10 @@ paths:
       tags:
       - Subscribe events
       summary: Subscribe events
-      description: "Streaming on-chain events for all blocks starting at the requested\
-        \ start block, up until the latest available block. Once the latest is reached,\
-        \ the stream will remain open and responses are sent for each new block as\
-        \ it becomes available."
+      description: |
+        IMPORTANT NOTE: This is a WebSocket connection, so the `ws://` or `wss://` schema should be used to subscribe to this endpoint.
+
+        This endpoint streams on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest block is reached, the stream will remain open, and responses will be sent for each new block as it becomes available.
       parameters:
       - name: start_height
         in: query
@@ -1088,26 +1088,38 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SubscribeEvents'
-        "1001":
-          description: Going Away
+        "400":
+          description: |
+            Bad Request
+
+            As OpenAPI does not support WebSocket description, the error code (1003) is actually returned in a close message instead of (400).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-        "1003":
-          description: Unsupported Data
+        "408":
+          description: |
+            Server Timeout
+
+            As OpenAPI does not support WebSocket description, this error code (1001) is actually returned in a close message instead of (408).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-        "1011":
-          description: Internal Server Error
+        "500":
+          description: |
+            Internal Server Error
+
+            As OpenAPI does not support WebSocket description, this error code (1011) is actually returned in a close message instead of (500).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-        "1013":
-          description: Try Agait Later
+        "503":
+          description: |
+            Service Unavailable
+
+            As OpenAPI does not support WebSocket description, this error code (1013) is actually returned in a close message instead of (503).
           content:
             application/json:
               schema:
@@ -2240,32 +2252,56 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+    "408ServerTimeout":
+      description: Server Timeout
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
     "500InternalServerError":
       description: Internal Server Error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    "1001CloseGoingAway":
-      description: Going Away
+    "503ServiceUnavailable":
+      description: Service Unavailable
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    "1003CloseUnsupportedData":
-      description: Unsupported Data
+    "400BadRequestWS":
+      description: |
+        Bad Request
+
+        As OpenAPI does not support WebSocket description, the error code (1003) is actually returned in a close message instead of (400).
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    "1011CloseInternalServerError":
-      description: Internal Server Error
+    "408ServerTimeoutWS":
+      description: |
+        Server Timeout
+
+        As OpenAPI does not support WebSocket description, this error code (1001) is actually returned in a close message instead of (408).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    "500InternalServerErrorWS":
+      description: |
+        Internal Server Error
+
+        As OpenAPI does not support WebSocket description, this error code (1011) is actually returned in a close message instead of (500).
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
-    "1013CloseTryAgaitLater":
-      description: Try Agait Later
+    "503ServiceUnavailableWS":
+      description: |
+        Service Unavailable
+
+        As OpenAPI does not support WebSocket description, this error code (1013) is actually returned in a close message instead of (503).
       content:
         application/json:
           schema:

diff --git a/openapi/go-client-generated/api_subscribe_events.go b/openapi/go-client-generated/api_subscribe_events.go
@@ -26,7 +26,7 @@ var (
 type SubscribeEventsApiService service
 /*
 SubscribeEventsApiService Subscribe events
-Streaming on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new block as it becomes available.
+IMPORTANT NOTE: This is a WebSocket connection, so the &#x60;ws://&#x60; or &#x60;wss://&#x60; schema should be used to subscribe to this endpoint.  This endpoint streams on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest block is reached, the stream will remain open, and responses will be sent for each new block as it becomes available. 
  * @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
  * @param optional nil or *SubscribeEventsApiSubscribeEventsGetOpts - Optional Parameters:
      * @param "StartHeight" (optional.Interface of BlockHeight) -  The block height of the events being streamed. Either provide this parameter or &#x60;start_block_id&#x60; parameter. This parameter is incompatible with &#x60;start_block_id&#x60; parameter.
@@ -137,7 +137,7 @@ func (a *SubscribeEventsApiService) SubscribeEventsGet(ctx context.Context, loca
 				newErr.model = v
 				return localVarReturnValue, localVarHttpResponse, newErr
 		}
-		if localVarHttpResponse.StatusCode == 1001 {
+		if localVarHttpResponse.StatusCode == 400 {
 			var v ModelError
 			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
 				if err != nil {
@@ -147,7 +147,7 @@ func (a *SubscribeEventsApiService) SubscribeEventsGet(ctx context.Context, loca
 				newErr.model = v
 				return localVarReturnValue, localVarHttpResponse, newErr
 		}
-		if localVarHttpResponse.StatusCode == 1003 {
+		if localVarHttpResponse.StatusCode == 408 {
 			var v ModelError
 			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
 				if err != nil {
@@ -157,7 +157,7 @@ func (a *SubscribeEventsApiService) SubscribeEventsGet(ctx context.Context, loca
 				newErr.model = v
 				return localVarReturnValue, localVarHttpResponse, newErr
 		}
-		if localVarHttpResponse.StatusCode == 1011 {
+		if localVarHttpResponse.StatusCode == 500 {
 			var v ModelError
 			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
 				if err != nil {
@@ -167,7 +167,7 @@ func (a *SubscribeEventsApiService) SubscribeEventsGet(ctx context.Context, loca
 				newErr.model = v
 				return localVarReturnValue, localVarHttpResponse, newErr
 		}
-		if localVarHttpResponse.StatusCode == 1013 {
+		if localVarHttpResponse.StatusCode == 503 {
 			var v ModelError
 			err = a.client.decode(&v, localVarBody, localVarHttpResponse.Header.Get("Content-Type"));
 				if err != nil {

diff --git a/openapi/go-client-generated/docs/SubscribeEventsApi.md b/openapi/go-client-generated/docs/SubscribeEventsApi.md
@@ -10,7 +10,7 @@ Method | HTTP request | Description
 > SubscribeEvents SubscribeEventsGet(ctx, optional)
 Subscribe events
 
-Streaming on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new block as it becomes available.
+IMPORTANT NOTE: This is a WebSocket connection, so the `ws://` or `wss://` schema should be used to subscribe to this endpoint.  This endpoint streams on-chain events for all blocks starting at the requested start block, up until the latest available block. Once the latest block is reached, the stream will remain open, and responses will be sent for each new block as it becomes available. 
 
 ### Required Parameters