Merge pull request #2134 from unboxed/documents-endpoint

Add authenticated documents endpoint for planning applications

engines/bops_api/app/controllers/bops_api/v2/documents_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BopsApi
+  module V2
+    class DocumentsController < AuthenticatedController
+      def show
+        @planning_application = find_planning_application params[:planning_application_id]
+        @documents = @planning_application.documents.active
+        @count = @documents.length
+
+        respond_to do |format|
+          format.json
+        end
+      end
+    end
+  end
+end

engines/bops_api/app/views/bops_api/v2/documents/show.json.jbuilder

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+json.key_format! camelize: :lower
+
+json.partial! "bops_api/v2/shared/application", planning_application: @planning_application
+
+json.files @documents do |document|
+  json.partial! "bops_api/v2/shared/document", planning_application: @planning_application, document:
+end
+json.metadata do
+  json.results @count
+  json.totalResults @count
+end
+
+if @planning_application.decision
+  json.partial! "bops_api/v2/shared/decision_notice", planning_application: @planning_application
+end

engines/bops_api/app/views/bops_api/v2/public/documents/show.json.jbuilder

@@ -5,16 +5,13 @@ json.key_format! camelize: :lower
 json.partial! "bops_api/v2/shared/application", planning_application: @planning_application
 
 json.files @documents do |document|
-  json.partial! "document", planning_application: @planning_application, document:
+  json.partial! "bops_api/v2/shared/document", planning_application: @planning_application, document:
 end
 json.metadata do
   json.results @count
   json.totalResults @count
 end
 
 if @planning_application.decision
-  json.decisionNotice do
-    json.name "decision-notice-#{@planning_application.reference_in_full}.pdf"
-    json.url main_app.decision_notice_api_v1_planning_application_url(@planning_application, id: @planning_application.reference, format: "pdf")
-  end
+  json.partial! "bops_api/v2/shared/decision_notice", planning_application: @planning_application
 end

engines/bops_api/app/views/bops_api/v2/shared/_decision_notice.json.jbuilder

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+json.decisionNotice do
+  json.name "decision-notice-#{planning_application.reference_in_full}.pdf"
+  json.url main_app.decision_notice_api_v1_planning_application_url(planning_application, id: planning_application.reference, format: "pdf")
+end

engines/bops_api/app/views/bops_api/v2/public/documents/_document.json.jbuilder → engines/bops_api/app/views/bops_api/v2/shared/_document.json.jbuilder

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 json.name document.name
-json.url main_app.api_v1_planning_application_document_url(@planning_application, document)
+json.url main_app.api_v1_planning_application_document_url(planning_application, document)
 json.type document.tags do |tag|
   json.value tag
   json.description I18n.t("document_tags.#{tag}")

engines/bops_api/config/routes.rb

@@ -20,6 +20,8 @@
         get :submission, on: :member
         get :search, on: :collection
 
+        resource :documents, only: [:show]
+
         scope module: "planning_applications" do
           resources :validation_requests, only: [:index]
         end

engines/bops_api/spec/requests/v2/documents_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "swagger_helper"
+
+RSpec.describe "BOPS documents API" do
+  let(:local_authority) { create(:local_authority, :default) }
+  let(:application_type) { create(:application_type, :householder) }
+  let(:public_document) { create(:document, :with_tags, validated: true, publishable: true) }
+  let(:private_document) { create(:document, :with_tags, validated: true, publishable: false) }
+
+  let(:token) { "bops_EjWSP1javBbvZFtRYiWs6y5orH4R748qapSGLNZsJw" }
+  let!(:api_user) { create(:api_user, token:, local_authority:) }
+
+  let(:planning_application) { create(:planning_application, :with_boundary_geojson, :with_press_notice, :determined, documents: [public_document, private_document], local_authority:, application_type:) }
+  let(:reference) { planning_application.reference }
+
+  around do |example|
+    travel_to("2025-10-22T10:30:00Z") { example.run }
+  end
+
+  path "/api/v2/planning_applications/{reference}/documents" do
+    get "Retrieves documents for a planning application" do
+      tags "Planning applications"
+      security [bearerAuth: []]
+      produces "application/json"
+
+      parameter name: :reference, in: :path, schema: {
+        type: :string,
+        description: "The planning application reference"
+      }
+
+      response "200", "returns a planning application's documents and decision notice given a reference" do
+        example "application/json", :default, example_fixture("documents.json")
+        schema "$ref" => "#/components/schemas/Documents"
+
+        let(:Authorization) { "Bearer bops_EjWSP1javBbvZFtRYiWs6y5orH4R748qapSGLNZsJw" }
+
+        run_test! do |response|
+          data = JSON.parse(response.body)
+          expect(data["application"]["reference"]).to eq(planning_application.reference)
+          expect(data["files"]).not_to be_empty
+          expect(data["decisionNotice"]["name"]).to eq("decision-notice-PlanX-25-00100-HAPP.pdf")
+          expect(data["decisionNotice"]["url"]).to eq("http://planx.example.com/api/v1/planning_applications/#{planning_application.reference}/decision_notice.pdf")
+        end
+      end
+
+      response "401", "with missing or invalid credentials" do
+        schema "$ref" => "#/components/schemas/UnauthorizedError"
+
+        example "application/json", :default, {
+          error: {
+            code: 401,
+            message: "Unauthorized"
+          }
+        }
+
+        let(:Authorization) { "Bearer invalid-credentials" }
+
+        run_test!
+      end
+
+      it "validates successfully against the example documents json" do
+        resolved_schema = load_and_resolve_schema(name: "documents", version: BopsApi::Schemas::DEFAULT_ODP_VERSION)
+        schemer = JSONSchemer.schema(resolved_schema)
+        example_json = example_fixture("documents.json")
+
+        expect(schemer.valid?(example_json)).to eq(true)
+      end
+    end
+  end
+end

engines/bops_api/spec/requests/v2/neighbour_responses_spec.rb

@@ -2,7 +2,7 @@
 
 require "swagger_helper"
 
-RSpec.describe "BOPS public API" do
+RSpec.describe "BOPS API" do
   let(:local_authority) { create(:local_authority, :default) }
   let(:application_type) { create(:application_type, :householder) }
   let(:document) { create(:document, :with_tags, validated: true, publishable: true) }