Merge pull request #672 from alphagov/CM-951-search-endpoint-for-api

(CM-951) Search endpoint for API

Author: pezholio

.github/workflows/check-open-api.yml

@@ -0,0 +1,41 @@
+name: Check OpenAPI documentation is up to date
+on:
+  workflow_call:
+
+jobs:
+    check-open-api:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+          with:
+            show-progress: false
+
+        - name: Setup Ruby
+          uses: ruby/setup-ruby@6aaa311d81eba98ae12eaffbcb63296ace0efcde # v1.307.0
+          with:
+            bundler-cache: true
+
+        - name: Setup Postgres
+          id: setup-postgres
+          uses: alphagov/govuk-infrastructure/.github/actions/setup-postgres@main
+
+        - name: Initialize database
+          env:
+            RAILS_ENV: test
+            TEST_DATABASE_URL: ${{ steps.setup-postgres.outputs.db-url }}
+          run: bundle exec rails db:setup
+
+        - name: Build OpenAPI documentation
+          run: bundle exec rake api:generate_swagger
+          env:
+            RAILS_ENV: test
+            TEST_DATABASE_URL: ${{ steps.setup-postgres.outputs.db-url }}
+
+        - name: Check for uncommitted changes
+          run: |
+            if git diff --exit-code; then
+              echo "No uncommitted changes detected."
+            else
+              echo "::error title=Uncommitted changes to OpenAPI docs::If these are your changes, run \\\`rake api:generate_swagger\\\` and commit the changes."
+              exit 1
+            fi

.github/workflows/ci.yml

@@ -29,6 +29,10 @@ jobs:
       security-events: write
       actions: read
 
+  check-open-api:
+    name: Check OpenAPI
+    uses: ./.github/workflows/check-open-api.yml
+
   lint-scss:
     name: Lint SCSS
     uses: ./.github/workflows/lintscss.yml

Gemfile

@@ -50,6 +50,7 @@ group :development, :test do
   gem "pry-byebug"
   gem "pry-rails"
   gem "rspec-rails"
+  gem "rswag-specs"
   gem "rubocop-govuk"
   gem "unparser", require: false
 end

Gemfile.lock

@@ -771,6 +771,11 @@ GEM
       rspec-mocks (>= 3.13.0, < 5.0.0)
       rspec-support (>= 3.13.0, < 5.0.0)
     rspec-support (3.13.7)
+    rswag-specs (2.17.0)
+      activesupport (>= 5.2, < 8.2)
+      json-schema (>= 2.2, < 7.0)
+      railties (>= 5.2, < 8.2)
+      rspec-core (>= 2.14)
     rubocop (1.86.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -995,6 +1000,7 @@ DEPENDENCIES
   record_tag_helper
   rinku
   rspec-rails
+  rswag-specs
   rubocop-govuk
   sentry-sidekiq
   shoulda-matchers
@@ -1037,7 +1043,6 @@ CHECKSUMS
   bootsnap (1.24.4) sha256=a4d939fc2cc5242a83d3a7cb4fb97743ac58475afe91e0600479a3df6f117541
   brakeman (8.0.4) sha256=7bf921fa9638544835df9aa7b3e720a9a72c0267f34f92135955edd80d4dcf6f
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
-  bundler (4.0.11) sha256=5bcec0fb78302e48d02ee46f10ee6e6942be647ba5b44a6d1ddfda9a240ce785
   byebug (13.0.0) sha256=d2263efe751941ca520fa29744b71972d39cbc41839496706f5d9b22e92ae05d
   capybara (3.40.0) sha256=42dba720578ea1ca65fd7a41d163dd368502c191804558f6e0f71b391054aeef
   capybara-playwright-driver (0.5.9) sha256=4c17fed20817b7e1bde2cfc8186e7bf5cd72017ce1aa695e35130f8e600e7282
@@ -1274,6 +1279,7 @@ CHECKSUMS
   rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
   rspec-rails (8.0.4) sha256=06235692fc0892683d3d34977e081db867434b3a24ae0dd0c6f3516bad4e22df
   rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rswag-specs (2.17.0) sha256=a3b2bdf6df89f8741fe4a4ee47ceb1e77dc13e1c96bbe07352117d6e61afa9e3
   rubocop (1.86.0) sha256=4ff1186fe16ebe9baff5e7aad66bb0ad4cabf5cdcd419f773146dbba2565d186
   rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   rubocop-capybara (2.22.1) sha256=ced88caef23efea53f46e098ff352f8fc1068c649606ca75cb74650970f51c0c

README.md

@@ -101,6 +101,20 @@ To run all linter with automatic formatting corrections, run:
 bundle exec rake:lint_autocorrect
 ```
 
+### API
+
+The code for the API is in the [`engines/api`](engines/api) directory. It is a Rails engine, and uses 
+[`rswag`](https://github.com/rswag/rswag) to generate [OpenAPI documentation](engines/api/swagger) from the tests in 
+[`engines/api/spec/requests`](engines/api/spec/requests).
+
+If you make any changes to the API, then you can regenerate the OpenAPI documentation by running:
+
+```
+rake api:generate_swagger
+```
+
+This will then update the OpenAPI documentation in [`engines/api/swagger`](engines/api/swagger).
+
 ### Further documentation
 
 See the [`docs/`](docs/) directory.

app/public/models/content_block.rb

@@ -16,9 +16,9 @@ def initialize(edition)
     @edition = edition
   end
 
-  delegate :id, :title, :state, :details, :document, :auth_bypass_id, :content_id, :render, to: :edition
-  delegate :schema, to: :document
-  delegate :embeddable_as_block?, to: :schema
+  delegate :id, :title, :state, :details, :document, :auth_bypass_id, :content_id, :render, :lead_organisation, to: :edition
+  delegate :schema, :embed_code, to: :document
+  delegate :embeddable_as_block?, :formats, to: :schema
 
   def block_type
     schema.name

app/public/queries/content_block/query.rb

@@ -0,0 +1,65 @@
+class ContentBlock
+  class Query
+    DEFAULT_PAGE_SIZE = 10
+    Result = Data.define(:blocks, :current_page, :total_pages, :total_count)
+
+    def self.call(filters = {})
+      new(filters).results
+    end
+
+    def initialize(filters)
+      @filters = filters
+    end
+
+    def results
+      Result.new(
+        blocks: paginated_results.map { |document| ContentBlock.new(document.most_recent_edition) },
+        current_page: paginated_results.current_page,
+        total_pages: paginated_results.total_pages,
+        total_count: paginated_results.total_count,
+      )
+    end
+
+  private
+
+    attr_reader :filters
+
+    def paginated_results
+      @paginated_results ||= unpaginated_results.page(page).per(DEFAULT_PAGE_SIZE)
+    end
+
+    def page
+      filters[:page].presence || 1
+    end
+
+    def unpaginated_results
+      Document.joins(:editions)
+              .merge(Edition.most_recent_for_document)
+              .merge(Edition.published)
+              .extending(Scopes)
+              .by_block_type(filters[:block_type])
+              .by_lead_organisation_id(filters[:lead_organisation_id])
+              .by_keyword(filters[:keyword])
+    end
+
+    module Scopes
+      def by_block_type(block_type)
+        return self if block_type.blank?
+
+        where("block_type = ?", block_type)
+      end
+
+      def by_lead_organisation_id(lead_organisation_id)
+        return self if lead_organisation_id.blank?
+
+        where("editions.lead_organisation_id = ?", lead_organisation_id)
+      end
+
+      def by_keyword(keyword)
+        return self if keyword.blank?
+
+        where("documents.id IN (?)", Document.with_keyword(keyword).pluck(:id))
+      end
+    end
+  end
+end

engines/api/app/controllers/api/blocks_controller.rb

@@ -0,0 +1,12 @@
+class Api::BlocksController < Api::ApplicationController
+  def search
+    result = ContentBlock::Query.call(filters)
+    render json: Api::ResultsPresenter.present(result, request.original_url)
+  end
+
+private
+
+  def filters
+    params.permit(:block_type, :lead_organisation_id, :keyword, :page)
+  end
+end

engines/api/app/presenters/api/block_presenter.rb

@@ -0,0 +1,29 @@
+class Api::BlockPresenter
+  class << self
+    def present(block)
+      new(block).present
+    end
+
+    def present_collection(blocks)
+      blocks.map { |block| present(block) }
+    end
+  end
+
+  def initialize(block)
+    @block = block
+  end
+
+  def present
+    {
+      title: @block.title,
+      block_type: @block.block_type,
+      organisation: {
+        name: @block.lead_organisation.name,
+        content_id: @block.lead_organisation.id,
+      },
+      state: "published",
+      embed_code: @block.embed_code,
+      formats: @block.formats,
+    }
+  end
+end

engines/api/app/presenters/api/results_presenter.rb

@@ -0,0 +1,73 @@
+module Api
+  class ResultsPresenter
+    class << self
+      def present(result, request_url)
+        new(result, request_url).present
+      end
+    end
+
+    def initialize(result, request_url)
+      @result = result
+      @request_url = URI.parse(request_url)
+    end
+
+    def present
+      {
+        total: result.total_count,
+        pages: result.total_pages,
+        current_page: result.current_page,
+        links:,
+        results: BlockPresenter.present_collection(result.blocks),
+      }
+    end
+
+  private
+
+    attr_reader :result, :request_url
+
+    def links
+      [previous_link, next_link, self_link].compact
+    end
+
+    def previous_link
+      return unless previous_page?
+
+      {
+        href: page_href(-1),
+        rel: "previous",
+      }
+    end
+
+    def next_link
+      return unless next_page?
+
+      {
+        href: page_href(1),
+        rel: "next",
+      }
+    end
+
+    def self_link
+      {
+        href: page_href(0),
+        rel: "self",
+      }
+    end
+
+    def page_href(offset)
+      request_url.tap { |url|
+        query_hash = Rack::Utils.parse_query(url.query)
+        query_hash["page"] = result.current_page + offset
+        url.query = Rack::Utils.build_query(query_hash)
+      }.to_s
+    end
+
+    def previous_page?
+      result.current_page > 1
+    end
+
+    def next_page?
+      result.current_page < result.total_pages
+    end
+  end
+end