Merge branch 'SpaceTradersAPI:main' into main

.github/workflows/validate.yml

@@ -0,0 +1,26 @@
+name: Validate OpenAPI Spec
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    name: Generate Clients
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Typescript Axios
+      uses: openapi-generators/openapitools-generator-action@v1
+      with:
+        generator: typescript-axios
+        openapi-file: ./reference/SpaceTraders.json
+
+    - name: Dart
+      uses: openapi-generators/openapitools-generator-action@v1
+      with:
+        generator: dart
+        openapi-file: ./reference/SpaceTraders.json

models/Agent.json

@@ -5,11 +5,12 @@
     "accountId": {
       "type": "string",
       "minLength": 1,
-      "description": "Account ID that is tied to this agent."
+      "description": "Account ID that is tied to this agent. Only included on your own agent."
     },
     "symbol": {
       "type": "string",
-      "minLength": 1,
+      "minLength": 3,
+      "maxLength": 14,
       "description": "Symbol of the agent."
     },
     "headquarters": {
@@ -26,13 +27,16 @@
       "type": "string",
       "minLength": 1,
       "description": "The faction the agent started with."
+    },
+    "shipCount": {
+      "type": "integer",
+      "description": "How many ships are owned by the agent."
     }
   },
   "required": [
-    "accountId",
     "symbol",
     "headquarters",
     "credits",
     "startingFaction"
   ]
-}
+}

models/FactionSymbols.json

@@ -1,6 +1,6 @@
 {
   "type": "string",
-  "description": "Faction symbol.",
+  "description": "The symbol of the faction.",
   "minLength": 1,
   "enum": [
     "COSMIC",

models/ShipModificationTransaction.json

@@ -0,0 +1,35 @@
+{
+  "type": "object",
+  "properties": {
+    "waypointSymbol": {
+      "type": "string",
+      "description": "The symbol of the waypoint where the transaction took place."
+    },
+    "shipSymbol": {
+      "type": "string",
+      "description": "The symbol of the ship that made the transaction."
+    },
+    "tradeSymbol": {
+      "type": "string",
+      "description": "The symbol of the trade good."
+    },
+    "totalPrice": {
+      "type": "integer",
+      "description": "The total price of the transaction.",
+      "minimum": 0
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The timestamp of the transaction."
+    }
+  },
+  "required": [
+    "waypointSymbol",
+    "shipSymbol",
+    "tradeSymbol",
+    "totalPrice",
+    "timestamp"
+  ],
+  "description": "Result of a transaction for a ship modification, such as installing a mount or a module."
+}

models/Survey.json

@@ -22,8 +22,7 @@
     "expiration": {
       "type": "string",
       "format": "date-time",
-      "description": "The date and time when the survey expires. After this date and time, the survey will no longer be available for extraction.",
+      "description": "The date and time when the survey expires. After this date and time, the survey will no longer be available for extraction."
-      "minimum": 0
     },
     "size": {
       "type": "string",

models/SystemFaction.json

@@ -2,9 +2,7 @@
   "type": "object",
   "properties": {
     "symbol": {
-      "type": "string",
+      "$ref": "./FactionSymbols.json"
-      "minLength": 1,
-      "description": "The symbol of the faction."
     }
   },
   "required": [

reference/SpaceTraders.json

@@ -79,7 +79,7 @@
                     },
                     "resetDate": {
                       "type": "string",
-                      "description": "The date and time when the game server was last reset."
+                      "description": "The date when the game server was last reset."
                     },
                     "description": {
                       "type": "string"
@@ -326,12 +326,7 @@
         },
         "summary": "Register New Agent",
         "tags": [],
-        "security": [
+        "security": []
-          {},
-          {
-            "AgentToken": []
-          }
-        ]
       }
     },
     "/systems": {
@@ -898,6 +893,120 @@
         ]
       }
     },
+    "/agents": {
+      "get": {
+        "description": "Fetch agents details.",
+        "operationId": "get-agents",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "../models/Agent.json"
+                      },
+                      "type": "array"
+                    },
+                    "meta": {
+                      "$ref": "../models/Meta.json"
+                    }
+                  },
+                  "required": [
+                    "data",
+                    "meta"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successfully fetched agents details."
+          }
+        },
+        "summary": "List Agents",
+        "tags": [
+          "Agents"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            },
+            "in": "query",
+            "name": "page",
+            "description": "What entry offset to request"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 20,
+              "default": 10
+            },
+            "in": "query",
+            "name": "limit",
+            "description": "How many entries to return per page"
+          }
+        ],
+        "security": [
+          {},
+          {
+            "AgentToken": []
+          }
+        ]
+      }
+    },
+    "/agents/{agentSymbol}": {
+      "get": {
+        "description": "Fetch agent details.",
+        "operationId": "get-agent",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "$ref": "../models/Agent.json"
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successfully fetched agent details."
+          }
+        },
+        "summary": "Get Public Agent",
+        "tags": [
+          "Agents"
+        ],
+        "parameters": [
+          {
+            "description": "The agent symbol",
+            "in": "path",
+            "name": "agentSymbol",
+            "required": true,
+            "schema": {
+              "default": "FEBA66",
+              "type": "string"
+            }
+          }
+        ],
+        "security": [
+          {},
+          {
+            "AgentToken": []
+          }
+        ]
+      }
+    },
     "/my/contracts": {
       "get": {
         "description": "Return a paginated list of all your contracts.",
@@ -1548,11 +1657,11 @@
           }
         },
         "responses": {
-          "200": {
+          "201": {
             "content": {
               "application/json": {
                 "schema": {
-                  "title": "Ship Refine 200 Response",
+                  "title": "Ship Refine 201 Response",
                   "type": "object",
                   "properties": {
                     "data": {
@@ -1584,7 +1693,11 @@
                                 "type": "integer",
                                 "description": "Amount of units of the good."
                               }
-                            }
+                            },
+                            "required": [
+                              "tradeSymbol",
+                              "units"
+                            ]
                           }
                         },
                         "consumed": {
@@ -1601,7 +1714,11 @@
                                 "type": "integer",
                                 "description": "Amount of units of the good."
                               }
-                            }
+                            },
+                            "required": [
+                              "tradeSymbol",
+                              "units"
+                            ]
                           }
                         }
                       }
@@ -2624,6 +2741,23 @@
       "post": {
         "description": "Refuel your ship by buying fuel from the local market.\n\nRequires the ship to be docked in a waypoint that has the `Marketplace` trait, and the market must be selling fuel in order to refuel.\n\nEach fuel bought from the market replenishes 100 units in your ship's fuel.\n\nShips will always be refuel to their frame's maximum fuel capacity when using this action.",
         "operationId": "refuel-ship",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "units": {
+                    "type": "integer",
+                    "description": "The amount of fuel to fill in the ship's tanks. When not specified, the ship will be refueled to its maximum fuel capacity. If the amount specified is greater than the ship's remaining capacity, the ship will only be refueled to its maximum fuel capacity. The amount specified is not in market units but in ship fuel units.",
+                    "example": "100",
+                    "minimum": 1
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "content": {
@@ -3013,7 +3147,7 @@
                           "$ref": "../models/ShipCargo.json"
                         },
                         "transaction": {
-                          "$ref": "../models/ShipyardTransaction.json"
+                          "$ref": "../models/ShipModificationTransaction.json"
                         }
                       }
                     }
@@ -3103,7 +3237,7 @@
                           "$ref": "../models/ShipCargo.json"
                         },
                         "transaction": {
-                          "$ref": "../models/ShipyardTransaction.json"
+                          "$ref": "../models/ShipModificationTransaction.json"
                         }
                       }
                     }