Swagger (#934)

* doc: Alpha Token API * Amend sidebar * Initial attempt, still broken --------- Co-authored-by: jlwllmr <95916148+jlwllmr@users.noreply.github.com>
Consensys · Jan 15, 2025 · 1786fe0 · 1786fe0
1 parent ce6a3b4
commit 1786fe0
Show file tree

Hide file tree

Showing 6 changed files with 1,365 additions and 108 deletions.
diff --git a/docs/api/token-api.mdx → docs/api/token-api/index.mdx b/docs/api/token-api.mdx → docs/api/token-api/index.mdx
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -1,3 +1,5 @@
+import * as Redocusaurus from 'redocusaurus';
+
 const lightCodeTheme = require("prism-react-renderer/themes/github");
 const darkCodeTheme = require("prism-react-renderer/themes/dracula");
 
@@ -83,6 +85,17 @@ const config = {
         },
       },
     ],
+    [
+      'redocusaurus',
+      {
+        specs: [
+          {
+            spec: './openapi.yaml',
+            route: 'api/token-api/reference',
+          },
+        ],
+      },
+    ],
   ],
 
   themeConfig:

diff --git a/openapi.yaml b/openapi.yaml
@@ -0,0 +1,281 @@
+openapi: 3.0.0
+paths:
+  /tokens/bonded:
+    get:
+      description: Retrieve a list of all tokens that have bonded
+      operationId: TokensController_findBonded
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successfully retrieved list of bonded tokens
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get all bonded tokens
+      tags:
+        - Tokens
+  /tokens/most-swapped:
+    get:
+      description: >-
+        Retrieve a list of the most frequently traded tokens on Linea over the
+        last 24 hours
+      operationId: TokensController_findMostSwapped
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: >-
+            Successfully retrieved list of most swapped tokens over the last 24
+            hours
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get most swapped tokens
+      tags:
+        - Tokens
+  /tokens:
+    get:
+      description: Retrieve a complete list of tokens available on Linea
+      operationId: TokensController_findAll
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successfully retrieved list of all tokens
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get all tokens
+      tags:
+        - Tokens
+  /tokens/top-winners:
+    get:
+      description: Retrieve tokens with the highest price increase in the last 24 hours
+      operationId: TokensController_findTopWinners
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successfully retrieved list of top performing tokens
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get top winners over the last 24 hours
+      tags:
+        - Tokens
+  /tokens/top-losers:
+    get:
+      description: Retrieve tokens with the highest price decrease in the last 24 hours
+      operationId: TokensController_findTopLosers
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successfully retrieved list of worst performing tokens
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get top losers over the last 24 hours
+      tags:
+        - Tokens
+  /tokens/new:
+    get:
+      description: Retrieve all tokens added over the last 24 hours
+      operationId: TokensController_findNewTokens
+      parameters:
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: List of new tokens
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TokenResponseDto'
+      summary: Get newly added tokens
+      tags:
+        - Tokens
+  /tokens/{contractAddress}:
+    get:
+      description: >-
+        Retrieve detailed information about a specific token using its contract
+        address
+      operationId: TokensController_findOne
+      parameters:
+        - name: contractAddress
+          required: true
+          in: path
+          description: The Ethereum contract address of the token
+          schema:
+            example: '0x1234567890123456789012345678901234567890'
+            type: string
+        - name: includePrices
+          required: false
+          in: query
+          description: Include token prices in the response
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successfully retrieved token information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenResponseDto'
+        '400':
+          description: Invalid contract address format
+        '404':
+          description: Token not found
+      summary: Get token by contract address
+      tags:
+        - Tokens
+info:
+  title: Linea Token API
+  description: >-
+    API to access token information on Linea, including prices, most traded
+    tokens, top gainers/losers over 24h and bonded tokens. Each endpoint can
+    optionally include price data.
+  version: 0.1.0
+  contact: {}
+tags: []
+servers: []
+components:
+  schemas:
+    PriceResponseDto:
+      type: object
+      properties:
+        price:
+          type: number
+          example: 1
+          description: Price of the token at a given date and time
+        date:
+          format: date-time
+          type: string
+          example: 2025-01-13T19:39:56.021Z
+          description: Date and time when the price was fetched
+      required:
+        - price
+        - date
+    TokenInfoResponseDto:
+      type: object
+      properties:
+        prices:
+          description: Prices history of the token
+          type: array
+          items:
+            $ref: '#/components/schemas/PriceResponseDto'
+        sells:
+          type: number
+          example: 1000
+          description: Number of sells
+        buys:
+          type: number
+          example: 2000
+          description: Number of buys
+        graduatedAt:
+          format: date-time
+          type: string
+          example: 2025-01-13T19:39:56.022Z
+          description: Graduation date of the token
+      required:
+        - prices
+        - sells
+        - buys
+        - graduatedAt
+    TokenResponseDto:
+      type: object
+      properties:
+        name:
+          type: string
+          example: Token name
+          description: Name of the token
+        symbol:
+          type: string
+          example: Token symbol
+          description: Symbol of the token
+        decimals:
+          type: number
+          example: 18
+          description: Number of decimals of the token
+        logo:
+          type: string
+          example: https://example.com/logo.png
+          description: URL of the token logo
+        contractAddress:
+          type: string
+          example: '0x1111111111111111111111111111111111111111'
+          description: Contract address of the token
+        currentPrice:
+          type: number
+          example: 1000
+          description: Current price of the token
+        priceUpdatedAt:
+          format: date-time
+          type: string
+          example: 2025-01-13T19:39:56.022Z
+          description: Date and time when the price was last updated
+        last24hVariation:
+          type: number
+          example: 0
+          description: Price variation in the last 24 hours
+        info:
+          description: Token information
+          allOf:
+            - $ref: '#/components/schemas/TokenInfoResponseDto'
+      required:
+        - name
+        - symbol
+        - decimals
+        - logo
+        - contractAddress
+        - currentPrice
+        - priceUpdatedAt
+        - last24hVariation
+        - info