swagger api docs

apps/api/app/controllers/api/events_controller.rb

@@ -4,7 +4,10 @@ class Api::EventsController < ApiController
   end
 
   api :GET, "/api/events", "List all events"
-  returns code: 200, desc: "Array of events"
+  returns code: 200, desc: "Array of events" do
+    property :name, String, desc: "Event name"
+    property :date, String, desc: "Event date (ISO 8601)"
+  end
   def index
     render json: EventService.new.index
   end

apps/api/app/controllers/api/members_controller.rb

@@ -4,7 +4,13 @@ class Api::MembersController < ApiController
   end
 
   api :GET, "/api/members", "List all team members"
-  returns code: 200, desc: "Array of team members"
+  returns code: 200, desc: "Array of team members" do
+    property :nick, String, desc: "Nickname"
+    property :real_nick, String, desc: "Real name"
+    property :motto, String, desc: "Motto / tagline"
+    property :avatar_filename, String, desc: "Avatar filename"
+    property :image_url, String, desc: "Avatar image URL (e.g. /api/image/123)"
+  end
   def index
     render json: MemberService.new.index
   end

apps/api/app/controllers/api/software_controller.rb

@@ -3,8 +3,56 @@ class Api::SoftwareController < ApiController
     short "Software catalog"
   end
 
+  def_param_group :external_link do
+    property :ID, Integer, desc: "Link ID"
+    property :softwareId, Integer, desc: "Parent software ID"
+    property :label, String, desc: "Link label (e.g. GitHub)"
+    property :url, String, desc: "Link URL"
+  end
+
+  def_param_group :software_image do
+    property :url, String, desc: "Image URL (e.g. /api/image/123)"
+    property :isDefault, :boolean, desc: "Default image flag"
+    property :position, Integer, desc: "Display order"
+  end
+
+  def_param_group :release do
+    property :ID, Integer, desc: "Release ID"
+    property :softwareId, Integer, desc: "Parent software ID"
+    property :version, String, desc: "Version string"
+    property :cartridgePath, String, desc: "Cartridge file path"
+    property :sourcePath, String, desc: "Source file path"
+    property :htmlFolderPath, String, desc: "HTML playable folder path"
+    property :docsFolderPath, String, desc: "Documentation folder path"
+    property :downloadCount, Integer, desc: "Download count for this release"
+  end
+
   api :GET, "/api/software", "List all software entries with releases"
-  returns code: 200, desc: "Array of software entries with nested releases"
+  returns code: 200, desc: "Wrapper object with softwares array" do
+    property :softwares, Array, desc: "Array of software entries" do
+      property :ID, Integer, desc: "Software ID"
+      property :name, String, desc: "Internal name"
+      property :title, String, desc: "Display title"
+      property :author, String, desc: "Author name"
+      property :desc, String, desc: "Short description"
+      property :story, String, desc: "Long description / story"
+      property :license, String, desc: "License type"
+      property :platform, String, desc: "Platform (tic80, love, ebitengine, c64)"
+      property :status, String, desc: "Status (active, inactive)"
+      property :highlighted, :boolean, desc: "Currently highlighted"
+      property :imageUrl, String, desc: "Default image URL"
+      property :externalLinks, Array, desc: "External links" do
+        property :ID, Integer, desc: "Link ID"
+        property :label, String, desc: "Link label"
+        property :url, String, desc: "Link URL"
+      end
+      property :images, Array, desc: "Image gallery" do
+        property :url, String, desc: "Image URL"
+        property :isDefault, :boolean, desc: "Default image flag"
+        property :position, Integer, desc: "Display order"
+      end
+    end
+  end
   def index
     render json: SoftwareService.new.index
   end

apps/api/app/controllers/api/software_highlighted_controller.rb

@@ -4,7 +4,33 @@ class Api::SoftwareHighlightedController < ApiController
   end
 
   api :GET, "/api/software/highlighted", "Get currently highlighted software entry"
-  returns code: 200, desc: "Highlighted software entry with releases"
+  returns code: 200, desc: "Highlighted software with releases and stats" do
+    property :software, Hash, desc: "Software entry" do
+      property :ID, Integer, desc: "Software ID"
+      property :name, String, desc: "Internal name"
+      property :title, String, desc: "Display title"
+      property :author, String, desc: "Author name"
+      property :desc, String, desc: "Short description"
+      property :story, String, desc: "Long description / story"
+      property :license, String, desc: "License type"
+      property :platform, String, desc: "Platform (tic80, love, ebitengine, c64)"
+      property :status, String, desc: "Status"
+      property :highlighted, :boolean, desc: "Highlighted flag"
+      property :imageUrl, String, desc: "Default image URL"
+    end
+    property :releases, Array, desc: "All releases" do
+      property :ID, Integer, desc: "Release ID"
+      property :version, String, desc: "Version string"
+      property :cartridgePath, String, desc: "Cartridge path"
+      property :sourcePath, String, desc: "Source path"
+      property :htmlFolderPath, String, desc: "HTML folder path"
+      property :docsFolderPath, String, desc: "Docs folder path"
+      property :downloadCount, Integer, desc: "Download count"
+    end
+    property :latestRelease, Hash, desc: "Latest release object"
+    property :webPlayableRelease, Hash, desc: "Web-playable release (if any)"
+    property :totalDownloads, Integer, desc: "Total download count across all releases"
+  end
   error code: 404, desc: "No highlighted software found"
   def index
     result = SoftwareHighlightedService.new.index

apps/api/app/controllers/api/swagger_controller.rb

@@ -0,0 +1,43 @@
+class Api::SwaggerController < ActionController::Base
+  layout false
+
+  def index
+    render html: swagger_html.html_safe
+  end
+
+  private
+
+  def swagger_html
+    <<~HTML
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Teletype Games API</title>
+        <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+        <style>
+          body { margin: 0; background: #fafafa; }
+          .swagger-ui .topbar { display: none; }
+        </style>
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+        <script>
+          SwaggerUIBundle({
+            url: '/api/docs.json',
+            dom_id: '#swagger-ui',
+            deepLinking: true,
+            presets: [
+              SwaggerUIBundle.presets.apis,
+              SwaggerUIBundle.SwaggerUIStandalonePreset
+            ],
+            layout: 'BaseLayout'
+          });
+        </script>
+      </body>
+      </html>
+    HTML
+  end
+end

apps/api/app/controllers/api/wiki_controller.rb

@@ -7,7 +7,24 @@ class Api::WikiController < ApiController
   param :tag, String, required: false, desc: "Filter by tag (blog, howto)"
   param :limit, :number, required: false, desc: "Limit number of results"
   param :body, String, required: false, desc: "Include body content (1 = yes)"
-  returns code: 200, desc: "Array of wiki pages"
+  returns code: 200, desc: "Wiki pages response" do
+    property :tag, String, desc: "Applied tag filter"
+    property :count, Integer, desc: "Number of pages returned"
+    property :pages, Array, desc: "Array of wiki pages" do
+      property :id, String, desc: "Page ID"
+      property :path, String, desc: "Page path"
+      property :title, String, desc: "Page title"
+      property :description, String, desc: "Short description"
+      property :createdAt, String, desc: "Created date (ISO 8601)"
+      property :updatedAt, String, desc: "Updated date (ISO 8601)"
+      property :locale, String, desc: "Locale code"
+      property :route, String, desc: "URL slug"
+      property :tags, Array, of: String, desc: "Tags"
+      property :render, String, desc: "Rendered HTML content"
+      property :content, String, desc: "Raw markdown content"
+    end
+    property :error, String, desc: "Error message (null on success)"
+  end
   # GET /api/wiki/pages?tag=blog|howto[&limit=30][&body=1]
   def index
     render json: WikiService.new.pages(

apps/api/app/controllers/update_controller.rb

@@ -6,10 +6,10 @@ class UpdateController < ApiController
 
   api :GET, "/update", "Update software version in database"
   param :secret, String, required: true, desc: "Authorization secret"
-  param :platform, String, required: false, desc: "Platform name"
+  param :platform, String, required: false, desc: "Platform (tic80, love, ebitengine, c64)"
   param :name, String, required: false, desc: "Software name"
   param :version, String, required: true, desc: "Version string"
-  returns code: 200, desc: "'Updated' on success"
+  returns code: 200, desc: "Plain text 'Updated'"
   error code: 401, desc: "Invalid secret"
   error code: 400, desc: "Version not provided or invalid arguments"
   error code: 500, desc: "Internal server error"