improve docs

jianoaix · Feb 18, 2025 · 5226cb8 · 5226cb8
1 parent d284aa1
commit 5226cb8
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 18 deletions.
diff --git a/disperser/dataapi/docs/v2/V2_docs.go b/disperser/dataapi/docs/v2/V2_docs.go
@@ -130,7 +130,7 @@ const docTemplateV2 = `{
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "Direction to fetch: 'forward' or 'backward' [default: forward]",
+                        "description": "Direction to fetch: 'forward' (oldest to newest) or 'backward' (newest to oldest) [default: forward]",
                         "name": "direction",
                         "in": "query",
                         "required": true
@@ -143,19 +143,19 @@ const docTemplateV2 = `{
                     },
                     {
                         "type": "string",
-                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than 'before' [default: before-1h]",
+                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than ` + "`" + `before` + "`" + ` [default: before-1h]",
                         "name": "after",
                         "in": "query"
                     },
                     {
                         "type": "string",
-                        "description": "Pagination cursor; for 'forward', fetches blobs from 'cursor' to 'before', for 'backward', fetches from 'after' to 'cursor' (all are exclusive) [default: empty]",
+                        "description": "Pagination cursor; for 'forward' direction, overides ` + "`" + `after` + "`" + ` and fetches blobs from ` + "`" + `cursor` + "`" + ` to ` + "`" + `before` + "`" + `; for 'backward' direction, overrides ` + "`" + `before` + "`" + ` and fetches blobs from ` + "`" + `cursor` + "`" + ` to ` + "`" + `before` + "`" + ` (all are exclusive) [default: empty]",
                         "name": "cursor",
                         "in": "query"
                     },
                     {
                         "type": "integer",
-                        "description": "Maximum number of blobs to fetch [default: 20; max: 1000]",
+                        "description": "Maximum number of blobs to return; if limit \u003c=0 or \u003e 1000, it's set to 1000 [default: 20; max: 1000]",
                         "name": "limit",
                         "in": "query"
                     }

diff --git a/disperser/dataapi/docs/v2/V2_swagger.json b/disperser/dataapi/docs/v2/V2_swagger.json
@@ -127,7 +127,7 @@
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "Direction to fetch: 'forward' or 'backward' [default: forward]",
+                        "description": "Direction to fetch: 'forward' (oldest to newest) or 'backward' (newest to oldest) [default: forward]",
                         "name": "direction",
                         "in": "query",
                         "required": true
@@ -140,19 +140,19 @@
                     },
                     {
                         "type": "string",
-                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than 'before' [default: before-1h]",
+                        "description": "Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than `before` [default: before-1h]",
                         "name": "after",
                         "in": "query"
                     },
                     {
                         "type": "string",
-                        "description": "Pagination cursor; for 'forward', fetches blobs from 'cursor' to 'before', for 'backward', fetches from 'after' to 'cursor' (all are exclusive) [default: empty]",
+                        "description": "Pagination cursor; for 'forward' direction, overides `after` and fetches blobs from `cursor` to `before`; for 'backward' direction, overrides `before` and fetches blobs from `cursor` to `before` (all are exclusive) [default: empty]",
                         "name": "cursor",
                         "in": "query"
                     },
                     {
                         "type": "integer",
-                        "description": "Maximum number of blobs to fetch [default: 20; max: 1000]",
+                        "description": "Maximum number of blobs to return; if limit \u003c=0 or \u003e 1000, it's set to 1000 [default: 20; max: 1000]",
                         "name": "limit",
                         "in": "query"
                     }

diff --git a/disperser/dataapi/docs/v2/V2_swagger.yaml b/disperser/dataapi/docs/v2/V2_swagger.yaml
@@ -675,7 +675,8 @@ paths:
   /blobs/feed:
     get:
       parameters:
-      - description: 'Direction to fetch: ''forward'' or ''backward'' [default: forward]'
+      - description: 'Direction to fetch: ''forward'' (oldest to newest) or ''backward''
+          (newest to oldest) [default: forward]'
         in: query
         name: direction
         required: true
@@ -686,17 +687,19 @@ paths:
         name: before
         type: string
       - description: 'Fetch blobs after this time, exclusive (ISO 8601 format, example:
-          2006-01-02T15:04:05Z); must be smaller than ''before'' [default: before-1h]'
+          2006-01-02T15:04:05Z); must be smaller than `before` [default: before-1h]'
         in: query
         name: after
         type: string
-      - description: 'Pagination cursor; for ''forward'', fetches blobs from ''cursor''
-          to ''before'', for ''backward'', fetches from ''after'' to ''cursor'' (all
-          are exclusive) [default: empty]'
+      - description: 'Pagination cursor; for ''forward'' direction, overides `after`
+          and fetches blobs from `cursor` to `before`; for ''backward'' direction,
+          overrides `before` and fetches blobs from `cursor` to `before` (all are
+          exclusive) [default: empty]'
         in: query
         name: cursor
         type: string
-      - description: 'Maximum number of blobs to fetch [default: 20; max: 1000]'
+      - description: 'Maximum number of blobs to return; if limit <=0 or > 1000, it''s
+          set to 1000 [default: 20; max: 1000]'
         in: query
         name: limit
         type: integer

diff --git a/disperser/dataapi/v2/blobs.go b/disperser/dataapi/v2/blobs.go
@@ -22,11 +22,11 @@ import (
 //	@Summary	Fetch blob feed in specified direction
 //	@Tags		Blobs
 //	@Produce	json
-//	@Param		direction	query		string	true	"Direction to fetch: 'forward' or 'backward' [default: forward]"
+//	@Param		direction	query		string	true	"Direction to fetch: 'forward' (oldest to newest) or 'backward' (newest to oldest) [default: forward]"
 //	@Param		before		query		string	false	"Fetch blobs before this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z) [default: now]"
-//	@Param		after		query		string	false	"Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than 'before' [default: before-1h]"
-//	@Param		cursor		query		string	false	"Pagination cursor; for 'forward', fetches blobs from 'cursor' to 'before', for 'backward', fetches from 'after' to 'cursor' (all are exclusive) [default: empty]"
-//	@Param		limit		query		int		false	"Maximum number of blobs to fetch [default: 20; max: 1000]"
+//	@Param		after		query		string	false	"Fetch blobs after this time, exclusive (ISO 8601 format, example: 2006-01-02T15:04:05Z); must be smaller than `before` [default: before-1h]"
+//	@Param		cursor		query		string	false	"Pagination cursor; for 'forward' direction, overides `after` and fetches blobs from `cursor` to `before`; for 'backward' direction, overrides `before` and fetches blobs from `cursor` to `before` (all are exclusive) [default: empty]"
+//	@Param		limit		query		int		false	"Maximum number of blobs to return; if limit <=0 or > 1000, it's set to 1000 [default: 20; max: 1000]"
 //	@Success	200			{object}	BlobFeedResponse
 //	@Failure	400			{object}	ErrorResponse	"error: Bad request"
 //	@Failure	404			{object}	ErrorResponse	"error: Not found"