complete API swagger documentation

app/controllers/api/base.rb

@@ -1,8 +1,9 @@
 require "grape"
-require "grape-swagger"
+require "ostruct"
 
 class Api::Base < Grape::API
   format :json
+  default_format :json
   content_type :json, "application/json"
 
   helpers do
@@ -17,9 +18,7 @@ class Api::Base < Grape::API
 
   resource :entries do
     desc "Return public entries in all languages",
-         is_array: true,
-         success: Api::Entities::Entry,
-         produces: [ "application/json" ]
+         attributes: OpenStruct.new(success: nil, produces: nil)
     params do
       optional :since,
                type: String,
@@ -46,14 +45,4 @@ class Api::Base < Grape::API
         )
     end
   end
-
-  add_swagger_documentation(
-    info: {
-      title: "Sanasto Wiki API",
-      description: "Public sync API for Sanasto Wiki glossary entries."
-    },
-    mount_path: "/swagger",
-    hide_documentation_path: true,
-    format: :json
-  )
 end

app/controllers/api/entities/entry.rb

@@ -1,15 +0,0 @@
-module Api
-  module Entities
-    class Entry < Grape::Entity
-      expose :id, documentation: { type: "integer", format: "int64", desc: "Entry ID." }
-      expose :category, documentation: { type: "string", desc: "Category label." }
-      expose :fi, documentation: { type: "string", desc: "Finnish term/definition.", allow_nil: true }
-      expose :en, documentation: { type: "string", desc: "English term/definition.", allow_nil: true }
-      expose :sv, documentation: { type: "string", desc: "Swedish term/definition.", allow_nil: true }
-      expose :no, documentation: { type: "string", desc: "Norwegian term/definition.", allow_nil: true }
-      expose :ru, documentation: { type: "string", desc: "Russian term/definition.", allow_nil: true }
-      expose :de, documentation: { type: "string", desc: "German term/definition.", allow_nil: true }
-      expose :updated_at, documentation: { type: "string", format: "date-time", desc: "Last update timestamp (ISO8601)." }
-    end
-  end
-end

app/controllers/api/swagger_controller.rb

@@ -0,0 +1,119 @@
+# config/routes.rb
+
+# app/controllers/api/swagger_controller.rb
+module Api
+  class SwaggerController < ApplicationController
+    def index
+      render json: {
+        openapi: "3.0.0",
+        info: {
+          title: "Sanasto Wiki API",
+          description: "Public sync API for Sanasto Wiki glossary entries.",
+          version: "1.0.0"
+        },
+        servers: [
+          {
+            url: "https://#{request.host}",
+            description: "Production server"
+          }
+        ],
+        paths: {
+          "/api/entries": {
+            get: {
+              summary: "Return public entries in all languages",
+              description: "Retrieve all active glossary entries with optional filtering by update timestamp",
+              tags: [ "Entries" ],
+              parameters: [
+                {
+                  name: "since",
+                  in: "query",
+                  description: "ISO8601 timestamp. Returns entries updated after this time.",
+                  required: false,
+                  schema: {
+                    type: "string",
+                    format: "date-time",
+                    example: "2024-01-01T00:00:00Z"
+                  }
+                }
+              ],
+              responses: {
+                "200": {
+                  description: "List of entries",
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "array",
+                        items: {
+                          "$ref": "#/components/schemas/Entry"
+                        }
+                      }
+                    }
+                  }
+                },
+                "400": {
+                  description: "Invalid since parameter",
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "object",
+                        properties: {
+                          error: { type: "string" }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        components: {
+          schemas: {
+            Entry: {
+              type: "object",
+              properties: {
+                id: {
+                  type: "integer",
+                  description: "Entry ID"
+                },
+                category: {
+                  type: "string",
+                  description: "Entry category"
+                },
+                fi: {
+                  type: "string",
+                  description: "Finnish translation"
+                },
+                en: {
+                  type: "string",
+                  description: "English translation"
+                },
+                sv: {
+                  type: "string",
+                  description: "Swedish translation"
+                },
+                no: {
+                  type: "string",
+                  description: "Norwegian translation"
+                },
+                ru: {
+                  type: "string",
+                  description: "Russian translation"
+                },
+                de: {
+                  type: "string",
+                  description: "German translation"
+                },
+                updated_at: {
+                  type: "string",
+                  format: "date-time",
+                  description: "Last update timestamp (ISO8601)"
+                }
+              }
+            }
+          }
+        }
+      }
+    end
+  end
+end