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,48 @@
+---
+# TODO:
+# https://openapi.tools
+# lint: https://github.com/stoplightio/spectral
+# generate version number (and other variables) during build/release
+# upload spec to release assets
+# generate SDKs
+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: The full address of your 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:
+    $ref: "./paths/config_api/apps.yml"
+  /api/logs:
+    $ref: "./paths/config_api/logs.yml"

api/paths/config_api/apps.yml

@@ -0,0 +1,18 @@
+---
+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"

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

src/confighttp.cpp

@@ -96,6 +96,7 @@ namespace confighttp {
    * @brief Send a 401 Unauthorized response.
    * @param response The HTTP response object.
    * @param request The HTTP request object.
+   * @todo Return JSON response.
    */
   void
   send_unauthorized(resp_https_t response, req_https_t request) {