Initial OpenAPI spec setup

Author: sorndotdev

.github/workflows/openapi-validate.yaml

@@ -0,0 +1,32 @@
+name: Validate OpenAPI Specs
+
+on:
+  push:
+    paths:
+      - 'components/**.yaml'
+      - 'services/**.yaml'
+      - 'responses/**.yaml'
+  pull_request:
+    paths:
+      - 'components/**.yaml'
+      - 'services/**.yaml'
+      - 'responses/**.yaml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install swagger-cli
+        run: npm install -g swagger-cli
+
+      - name: Validate OpenAPI spec
+        run: |
+          swagger-cli validate main.yaml --verbose

.github/workflows/update-website.yaml

@@ -0,0 +1,28 @@
+name: Update Website Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'openapi.json'
+      - 'openapi.yaml'
+      - 'docs/**'
+      - '*.md'
+
+jobs:
+  update-website:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout openapi repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Trigger website deployment
+        run: |
+          curl -X POST \
+            -H "Authorization: token ${{ secrets.WEBSITE_DEPLOY_TOKEN }}" \
+            -H "Accept: application/vnd.github.v3+json" \
+            https://api.github.com/repos/marketdataapi/website/dispatches \
+            -d '{"event_type": "openapi-updated", "client_payload": {"sha": "${{ github.sha }}", "ref": "${{ github.ref }}"}}'
+

.gitignore

@@ -0,0 +1,4 @@
+.idea
+dist/
+output.txt
+setup.txt

README.md

@@ -0,0 +1,24 @@
+## MarketDataAPI.com — OpenAPI Specifications
+
+# Overview
+
+This repository hosts the official OpenAPI (Swagger) specification files for **MarketDataAPI.com**, enabling
+standardized integration with MarketDataAPI’s financial data services.
+
+* Specification standard: **OpenAPI 3.1.0**
+* API reference: [https://www.marketdataapi.com/docs](https://www.marketdataapi.com/docs)
+
+# Compatibility
+
+* Fully compliant with **OpenAPI Specification**.
+* Suitable for code generation, validation, documentation, and client/server scaffolding.
+
+# Support & Issue Tracking
+
+* Bugs, technical issues, and feature requests: **GitHub Issues**.
+* General inquiries and assistance: [https://www.marketdataapi.com/help](https://www.marketdataapi.com/help).
+
+# License
+
+* Open source under the **MIT License**.
+* See the `LICENSE` file for full terms.

components/parameters/path.yaml

@@ -0,0 +1,13 @@
+openapi: 3.1.0
+info:
+  title: MarketDataAPI.com - Path Parameters
+  version: '1'
+
+components:
+  parameters:
+    InstrumentIdentifierPathParam:
+      name: identifier
+      in: path
+      required: true
+      schema:
+        $ref: '../schemas/instrument.yaml#/components/schemas/InstrumentIdentifier'

components/parameters/query.yaml

@@ -0,0 +1,27 @@
+openapi: 3.1.0
+info:
+  title: MarketDataAPI.com - Query Parameters
+  version: '1'
+
+components:
+  parameters:
+    LimitQueryParam:
+      name: limit
+      in: query
+      description: Maximum number of items to return
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+
+    OffsetQueryParam:
+      name: offset
+      in: query
+      description: Pagination offset
+      required: false
+      schema:
+        type: integer
+        minimum: 0
+        default: 0

components/responses.yaml

@@ -0,0 +1,65 @@
+openapi: 3.1.0
+info:
+  title: MarketDataAPI.com - Shared Responses
+  version: '1'
+
+components:
+  responses:
+    BadRequest:
+      description: Invalid request parameters
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+          examples:
+            invalidQuery:
+              summary: Invalid search query
+              value:
+                type: 'https://marketdataapi.com/errors/bad-request'
+                title: 'Invalid Request Parameters'
+                status: 400
+                detail: 'Query parameter ''q'' must be at least 1 character long'
+                instance: '/v1/instruments?q='
+                code: 'validation/invalid-parameter'
+
+    Unauthorized:
+      description: Authentication failed
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+
+    TooManyRequests:
+      description: Rate limit exceeded
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+
+    PaymentRequired:
+      description: Subscription required for this endpoint
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+
+    Forbidden:
+      description: Authenticated but forbidden
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'
+
+    InternalServerError:
+      description: Unexpected server error
+      content:
+        application/problem+json:
+          schema:
+            $ref: './schemas/error.yaml#/components/schemas/ProblemDetail'

components/schemas/base.yaml

@@ -0,0 +1,58 @@
+openapi: 3.1.0
+info:
+  title: MarketDataAPI.com - Base Schemas
+  version: '1'
+
+components:
+  schemas:
+    Meta:
+      type: object
+      properties:
+        total:
+          type: integer
+          minimum: 0
+          example: 100
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          example: 20
+        offset:
+          type: integer
+          minimum: 0
+          example: 40
+        took_ms:
+          type: integer
+          description: Total execution time in milliseconds
+          minimum: 0
+          example: 47
+
+    Links:
+      type: object
+      properties:
+        self:
+          type: string
+          format: uri-reference
+          example: '/v1/instruments?limit=20&offset=40'
+        next:
+          type: string
+          format: uri-reference
+          example: '/v1/instruments?limit=20&offset=60'
+        prev:
+          type: string
+          format: uri-reference
+          example: '/v1/instruments?limit=20&offset=20'
+
+    BaseCollection:
+      type: object
+      required: [meta, links, data]
+      properties:
+        meta:
+          $ref: '#/components/schemas/Meta'
+        links:
+          $ref: '#/components/schemas/Links'
+        data:
+          type: array
+          items:
+            type: object
+          description: The primary data collection; structure varies by endpoint