complete API swagger documentation

2026-02-04 01:33:02 +01:00
parent a139bde102
commit 441caabb98
6 changed files with 131 additions and 47 deletions
@@ -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