feat(api): add openapi specification

api/models/app.yml

@@ -0,0 +1,48 @@
+---
+type: object
+required:
+  - name
+properties:
+  name:
+    type: string
+    description: Application Name, as shown on Moonlight
+  output:
+    type: string
+    description: The file where the output of the command is stored, if it is not specified, the output is ignored
+  cmd:
+    $ref: "cmd.yml"
+    description: The main application to start. If blank, no application will be started.
+  exclude-global-prep-cmd:
+    $ref: "../types/boolean.yml"
+    description: Enable/Disable the execution of Global Prep Commands for this application.
+  elevated:
+    $ref: "../types/boolean.yml"
+    description: Run the application as an elevated process.
+  auto-detach:
+    $ref: "../types/boolean.yml"
+    description: Continue streaming if the application exits quickly
+  wait-all:
+    $ref: "../types/boolean.yml"
+    description: Continue streaming until all app processes exit
+  exit-timeout:
+    $ref: "../types/integer.yml"
+    description: Number of seconds to wait for all app processes to gracefully exit when requested to quit.
+  image-path:
+    type: string
+    description: |
+      Application icon/picture/image path that will be sent to client. Image must be a PNG file.
+      If not set, Sunshine will send default box image.
+  working-dir:
+    type: string
+    description: |
+      The working directory that should be passed to the process.
+      For example, some applications use the working directory to search for configuration files.
+      If not set, Sunshine will default to the parent directory of the command
+  prep-cmd:
+    type: array
+    items:
+      $ref: "prep-cmd.yml"
+  detached:
+    type: array
+    items:
+      $ref: "cmd.yml"

api/models/cmd.yml

@@ -0,0 +1,3 @@
+---
+type: string
+description: Command to execute

api/models/prep-cmd.yml

@@ -0,0 +1,16 @@
+---
+type: object
+required:
+  - do
+  - undo
+  - elevated
+properties:
+  do:
+    $ref: "cmd.yml"
+    description: Command to run before the application starts.
+  undo:
+    $ref: "cmd.yml"
+    description: Command to run after the application exits.
+  elevated:
+    $ref: "../types/boolean.yml"
+    description: Run the command as an elevated process.

api/openapi.yml

@@ -0,0 +1,50 @@
+---
+# https://openapi.tools
+
+openapi: 3.1.0
+
+info:
+  title: Sunshine
+  summary: Self-hosted game stream host for Moonlight.
+  version: 0.0.0
+  contact:
+    name: LizardByte
+    url: https://app.lizardbyte.dev/support
+  license:
+    name: GNU General Public License v3.0 only
+    url: https://github.com/LizardByte/Sunshine/blob/master/LICENSE
+
+servers:
+  - url: "https://{host}:{port}"
+    description: Sunshine server
+    variables:
+      host:
+        default: "localhost"
+        description: The IP address or hostname of your Sunshine server
+      port:
+        default: "47990"
+        description: The Sunshine config port number
+
+security:
+  - basicAuth: []
+
+components:
+  securitySchemes:
+    # TODO: update when JWT is implemented (https://github.com/LizardByte/Sunshine/pull/2995)
+    # https://swagger.io/specification/#security-scheme-object-examples
+    basicAuth:
+      description: HTTP Basic authentication
+      type: http
+      scheme: basic
+
+paths:
+  /api/apps:
+    get:
+      $ref: "./paths/config_api/apps.yml#/get"
+    post:
+      $ref: "./paths/config_api/apps.yml#/post"
+  /api/apps/{index}:
+    delete:
+      $ref: "./paths/config_api/apps.yml#/delete"
+  /api/logs:
+    $ref: "./paths/config_api/logs.yml"

api/paths/config_api/apps.yml

@@ -0,0 +1,160 @@
+---
+get:
+  summary: Get the list of available applications.
+  description: |
+    Get the list of available applications.
+  operationId: getApps
+  tags:
+    - Apps
+  responses:
+    $ref: "../../responses/authorize.yml"
+    "200":
+      description: A list of available applications.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "../../models/app.yml"
+
+post:
+  summary: Save an application.
+  description: |
+    Save an application.
+    To save a new application the index must be `-1`.
+    To update an existing application, you must provide the current index of the application.
+  operationId: postApps
+  tags:
+    - Apps
+  parameters:
+    - name: index
+      in: query
+      description: The index of the application to update. If the index is -1, a new application will be created.
+      required: true
+      schema:
+        type: integer
+        format: int32
+    - name: name
+      in: query
+      description: Application Name
+      required: false
+      schema:
+        type: string
+    - name: output
+      in: query
+      description: Log Output Path
+      required: false
+      schema:
+        type: string
+    - name: cmd
+      in: query
+      description: Command to run the application
+      required: false
+      schema:
+        $ref: "../../models/cmd.yml"
+    - name: exclude-global-prep-cmd
+      in: query
+      description: Enable/Disable the execution of Global Prep Commands for this application.
+      required: false
+      schema:
+        type: boolean
+    - name: elevated
+      in: query
+      description: Run the application as an elevated process.
+      required: false
+      schema:
+        type: boolean
+    - name: auto-detach
+      in: query
+      description: Continue streaming if the application exits quickly
+      required: false
+      schema:
+        type: boolean
+    - name: wait-all
+      in: query
+      description: Continue streaming until all app processes exit
+      required: false
+      schema:
+        type: boolean
+    - name: exit-timeout
+      in: query
+      description: Number of seconds to wait for all app processes to gracefully exit when requested to quit.
+      required: false
+      schema:
+        type: integer
+        format: int32
+    - name: prep-cmd
+      in: query
+      description: Commands to run before the main application
+      required: false
+      schema:
+        type: array
+        items:
+          $ref: "../../models/prep-cmd.yml"
+    - name: detached
+      in: query
+      description: Commands to run in detached processes
+      required: false
+      schema:
+        type: array
+        items:
+        $ref: "../../models/cmd.yml"
+    - name: image-path
+      in: query
+      description: Full path to the application image. Must be a png file.
+      required: false
+      schema:
+        type: string
+    - name: working-dir
+      in: query
+      description: The working directory that should be passed to the process.
+      required: false
+      schema:
+        type: string
+  responses:
+    $ref: "../../responses/authorize.yml"
+    "200":
+      description: The application was saved successfully.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                type: string
+                example: true
+    "400":
+      $ref: "../../responses/400.yml"
+
+delete:
+  summary: Delete an application.
+  description: |
+    Delete an application.
+  operationId: deleteApps
+  tags:
+    - Apps
+  parameters:
+    - name: index
+      in: path
+      description: The index of the application to delete.
+      required: true
+      schema:
+        type: integer
+        format: int32
+  responses:
+    $ref: "../../responses/authorize.yml"
+    "200":
+      description: The application was deleted successfully.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                type: string
+                example: true
+              result:
+                type: string
+                example: application 9999 deleted
+    "400":
+      $ref: "../../responses/400.yml"

api/paths/config_api/logs.yml

@@ -0,0 +1,17 @@
+---
+get:
+  summary: Get the logs from the log file.
+  description: |
+    Get the logs from the log file.
+  operationId: getLogs
+  tags:
+    - Logs
+  responses:
+    $ref: "../../responses/authorize.yml"
+    "200":
+      description: The contents of the log file.
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: '[2025-01-15 17:07:58.131]: Info: Sunshine version: v...'

api/responses/400.yml

@@ -0,0 +1,18 @@
+---
+description: Bad Request - A parameter was not specified, or was specified incorrectly.
+content:
+  application/json:
+    schema:
+      x-speakeasy-name-override: BadRequest
+      type: object
+      properties:
+        status_code:
+          type: integer
+          format: int32
+          example: 400
+        status:
+          type: string
+          example: false
+        error:
+          type: string
+          example: Bad Request

api/responses/401.yml

@@ -0,0 +1,8 @@
+---
+description: Unauthorized - The request requires user authentication.
+content:
+  # TODO: return JSON response.
+  text/plain:
+    schema:
+      type: string
+      example: ''

api/responses/403.yml

@@ -0,0 +1,8 @@
+---
+description: Forbidden - The server understood the request, but is refusing to fulfill it.
+content:
+  # TODO: return JSON response.
+  text/plain:
+    schema:
+      type: string
+      example: ''

api/responses/404.yml

@@ -0,0 +1,14 @@
+---
+description: Not Found - The requested resource could not be found.
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        status_code:
+          type: integer
+          format: int32
+          example: 404
+        error:
+          type: string
+          example: Not Found

api/responses/authorize.yml

@@ -0,0 +1,5 @@
+---
+401:
+  $ref: "401.yml"
+403:
+  $ref: "403.yml"

api/types/boolean.yml

@@ -0,0 +1,3 @@
+---
+type: string
+description: Boolean value as a string

api/types/integer.yml

@@ -0,0 +1,3 @@
+---
+type: string
+description: Integer value as a string