complete API swagger documentation

Gemfile

@@ -19,7 +19,6 @@ gem "stimulus-rails"
 # Build JSON APIs with ease [https://github.com/rails/jbuilder]
 gem "jbuilder"
 gem "grape"
-gem "grape-swagger"
 gem "rswag-ui"
 gem "caxlsx"
 gem "caxlsx_rails"
@@ -47,6 +46,9 @@ gem "thruster", require: false
 # Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
 gem "image_processing", "~> 1.2"
 
+# Pagination [https://github.com/ddnexus/pagy]
+gem "pagy", "~> 8.0"
+
 group :development, :test do
   # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"

Gemfile.lock

@@ -120,9 +120,6 @@ GEM
     docile (1.4.1)
     dotenv (3.2.0)
     drb (2.2.3)
-    dry-configurable (1.3.0)
-      dry-core (~> 1.1)
-      zeitwerk (~> 2.6)
     dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
@@ -151,15 +148,12 @@ GEM
       raabro (~> 1.4)
     globalid (1.3.0)
       activesupport (>= 6.1)
-    grape (3.1.1)
+    grape (2.4.0)
-      activesupport (>= 7.1)
+      activesupport (>= 6.1)
-      dry-configurable
       dry-types (>= 1.1)
       mustermann-grape (~> 1.1.0)
       rack (>= 2)
       zeitwerk
-    grape-swagger (2.1.3)
-      grape (>= 1.7, < 4.0)
     htmlentities (4.4.2)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
@@ -178,7 +172,7 @@ GEM
     jbuilder (2.14.1)
       actionview (>= 7.0.0)
       activesupport (>= 7.0.0)
-    json (2.18.0)
+    json (2.18.1)
     kamal (2.10.1)
       activesupport (>= 7.0)
       base64 (~> 0.2)
@@ -232,6 +226,7 @@ GEM
     nokogiri (1.19.0-x86_64-linux-gnu)
       racc (~> 1.4)
     ostruct (0.6.3)
+    pagy (8.6.3)
     parallel (1.27.0)
     parser (3.3.10.1)
       ast (~> 2.4.1)
@@ -425,11 +420,11 @@ DEPENDENCIES
   caxlsx_rails
   debug
   grape
-  grape-swagger
   image_processing (~> 1.2)
   importmap-rails
   jbuilder
   kamal
+  pagy (~> 8.0)
   propshaft
   puma (>= 5.0)
   rails (~> 8.1.2)
@@ -485,7 +480,6 @@ CHECKSUMS
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   dotenv (3.2.0) sha256=e375b83121ea7ca4ce20f214740076129ab8514cd81378161f11c03853fe619d
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  dry-configurable (1.3.0) sha256=882d862858567fc1210d2549d4c090f34370fc1bb7c5c1933de3fe792e18afa8
   dry-core (1.2.0) sha256=0cc5a7da88df397f153947eeeae42e876e999c1e30900f3c536fb173854e96a1
   dry-inflector (1.3.1) sha256=7fb0c2bb04f67638f25c52e7ba39ab435d922a3a5c3cd196120f63accb682dcc
   dry-logic (1.6.0) sha256=da6fedbc0f90fc41f9b0cc7e6f05f5d529d1efaef6c8dcc8e0733f685745cea2
@@ -497,8 +491,7 @@ CHECKSUMS
   ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
   fugit (1.12.1) sha256=5898f478ede9b415f0804e42b8f3fd53f814bd85eebffceebdbc34e1107aaf68
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11
-  grape (3.1.1) sha256=774f16782d917a90e69de0499dfaab571e5ad967569ac066a2b0b918af12de69
+  grape (2.4.0) sha256=3d59673e80f11d49ba86270b78344e5348dc057b318c2bbc1c01f3532f9b6aec
-  grape-swagger (2.1.3) sha256=9ee955ada77c10ea2f2d2da5edcc4fc3cddcc40a6936f1b2558ee7b44e0f1153
   htmlentities (4.4.2) sha256=bbafbdf69f2eca9262be4efef7e43e6a1de54c95eb600f26984f71d2fe96c5c3
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   image_processing (1.14.0) sha256=754cc169c9c262980889bec6bfd325ed1dafad34f85242b5a07b60af004742fb
@@ -506,7 +499,7 @@ CHECKSUMS
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
   jbuilder (2.14.1) sha256=4eb26376ff60ef100cb4fd6fd7533cd271f9998327e86adf20fd8c0e69fabb42
-  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  json (2.18.1) sha256=fe112755501b8d0466b5ada6cf50c8c3f41e897fa128ac5d263ec09eedc9f986
   kamal (2.10.1) sha256=53b7ecb4c33dd83b1aedfc7aacd1c059f835993258a552d70d584c6ce32b6340
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
@@ -531,6 +524,7 @@ CHECKSUMS
   nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
   nokogiri (1.19.0-x86_64-linux-gnu) sha256=f482b95c713d60031d48c44ce14562f8d2ce31e3a9e8dd0ccb131e9e5a68b58c
   ostruct (0.6.3) sha256=95a2ed4a4bd1d190784e666b47b2d3f078e4a9efda2fccf18f84ddc6538ed912
+  pagy (8.6.3) sha256=537b2ee3119f237dd6c4a0d0a35c67a77b9d91ebb9d4f85e31407c2686774fb2
   parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
   parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6

app/controllers/api/base.rb

@@ -1,9 +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
@@ -45,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/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

app/controllers/application_controller.rb

@@ -1,5 +1,6 @@
 class ApplicationController < ActionController::Base
   include BotBlocker
+  include Pagy::Backend
 
   # Changes to the importmap will invalidate the etag for HTML responses
   stale_when_importmap_changes

app/controllers/entries_controller.rb

@@ -6,8 +6,6 @@ class EntriesController < ApplicationController
     @category = params[:category].presence
     @query = params[:q].to_s.strip
     @starts_with = params[:starts_with].presence
-    @page = [ params[:page].to_i, 1 ].max
-    @per_page = 25
 
     entries_scope = Entry.active_entries
     entries_scope = entries_scope.with_category(@category)
@@ -16,9 +14,8 @@ class EntriesController < ApplicationController
     entries_scope = entries_scope.alphabetical_for(@language_code) if @query.blank? && @starts_with.blank? && @language_code.present?
     entries_scope = entries_scope.order(created_at: :desc) if entries_scope.order_values.empty?
 
-    @total_entries = entries_scope.count
+    @pagy, @entries = pagy(entries_scope, items: 25)
-    @total_pages = (@total_entries.to_f / @per_page).ceil
+    @total_entries = @pagy.count
-    @entries = entries_scope.offset((@page - 1) * @per_page).limit(@per_page)
 
     @entry_count = Entry.active_entries.count
     @requested_count = Entry.requested.count

app/helpers/application_helper.rb

@@ -1,4 +1,6 @@
 module ApplicationHelper
+  include Pagy::Frontend
+
   def language_name(code)
     supported_languages.find { |l| l.code == code }&.name
   end

app/views/entries/_results.html.erb

@@ -86,17 +86,19 @@
     </div>
 
     <div class="flex items-center justify-between mt-4 text-sm text-slate-600">
-      <div>Page <%= @page %> of <%= [@total_pages, 1].max %></div>
+      <div><%= pagy_info(@pagy) %></div>
       <div class="flex items-center gap-2">
-        <% previous_page = @page > 1 ? @page - 1 : nil %>
+        <%
-        <% next_page = @page < @total_pages ? @page + 1 : nil %>
+          pagination_params = { q: @query.presence, category: @category.presence, language: @language_code.presence, starts_with: @starts_with.presence }.compact
-        <% pagination_params = { q: @query.presence, category: @category.presence, language: @language_code.presence, starts_with: @starts_with.presence }.compact %>
+          prev_url = @pagy.prev ? entries_path(pagination_params.merge(page: @pagy.prev)) : nil
-        <%= link_to "Previous", previous_page ? entries_path(pagination_params.merge(page: previous_page)) : "#",
+          next_url = @pagy.next ? entries_path(pagination_params.merge(page: @pagy.next)) : nil
-                    class: "px-3 py-1.5 rounded-md border border-slate-200 #{previous_page ? 'hover:border-indigo-300' : 'text-slate-300 cursor-not-allowed'}",
+        %>
-                    data: { turbo_stream: true } %>
+        <%= link_to "Previous", prev_url || "#",
-        <%= link_to "Next", next_page ? entries_path(pagination_params.merge(page: next_page)) : "#",
+              class: "px-3 py-1.5 rounded-md border border-slate-200 #{'opacity-50 pointer-events-none' unless prev_url}",
-                    class: "px-3 py-1.5 rounded-md border border-slate-200 #{next_page ? 'hover:border-indigo-300' : 'text-slate-300 cursor-not-allowed'}",
+              data: (prev_url ? { turbo_stream: true } : {}) %>
-                    data: { turbo_stream: true } %>
+        <%= link_to "Next", next_url || "#",
+              class: "px-3 py-1.5 rounded-md border border-slate-200 #{'opacity-50 pointer-events-none' unless next_url}",
+              data: (next_url ? { turbo_stream: true } : {}) %>
       </div>
     </div>
   </div>

config/initializers/pagy.rb

@@ -0,0 +1,6 @@
+# Pagy Configuration
+require "pagy/extras/overflow"
+
+Pagy::DEFAULT[:items] = 25  # Match current 25 items per page
+Pagy::DEFAULT[:page_param] = :page
+Pagy::DEFAULT[:overflow] = :last_page

config/routes.rb

@@ -1,6 +1,10 @@
 Rails.application.routes.draw do
   # Define your application routes per the DSL in https://guides.rubyonrails.org/routing.html
 
+  mount Api::Base => "/api"
+  get "/api/swagger", to: "api/swagger#index"
+  mount Rswag::Ui::Engine => "/api"
+
   # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
   # Can be used by load balancers and uptime monitors to verify that the app is live.
   get "up" => "rails/health#show", as: :rails_health_check
@@ -51,9 +55,6 @@ Rails.application.routes.draw do
     end
   end
 
-  mount Api::Base => "/api"
-  mount Rswag::Ui::Engine => "/api"
-
   resources :entries do
     resources :comments, only: [ :create ]
     collection do

test/controllers/entries_controller_test.rb

@@ -41,7 +41,8 @@ class EntriesControllerTest < ActionDispatch::IntegrationTest
   test "should paginate results" do
     get entries_url, params: { page: 2 }
     assert_response :success
-    assert_select "div", text: /Page 2 of/i
+    assert_not_nil assigns(:pagy)
+    assert_select "div", text: /Displaying/i
   end
 
   test "should handle invalid language code" do

test/system/public_browsing_test.rb

@@ -102,7 +102,7 @@ class PublicBrowsingTest < ApplicationSystemTestCase
     visit root_path
 
     assert_selector ".entry-row", count: 25
-    assert_link "2"
+    assert_link "Next"
   end
 
   test "visitor sees entry statistics" do