CLDC-542: OpenAPI documentation (#53)

* API doc init * Rename docs dir * Try YAML * Index page * Chars * Case Log * Summaries * Add to readme * Add sandbox server * Dry * Add some 422 examples * GET doesn't have a request body * Accept header * Add show method to JSON API and document not found response * Set header default * Add some field guidance * Don't need a default value if we only have one enum
3 years ago · ac5223a09e
13 changed files with 1208 additions and 4 deletions
--- a/README.md
+++ b/README.md
@ -4,6 +4,12 @@

 This is the codebase for the Ruby on Rails app that will handle the submission of Lettings and Sales of Social Housing in England data.

+
+## API documentation
+
+API documentation can be found here: https://communitiesuk.github.io/mhclg-data-collection-beta/. This is driven by [OpenAPI docs](docs/api/DLUHC-CORE-Data.v1.json)
+
+
 ## Required Setup

 Pre-requisites:
--- a/app/controllers/case_logs_controller.rb
+++ b/app/controllers/case_logs_controller.rb
@ -33,9 +33,18 @@ class CaseLogsController < ApplicationController
    end
  end

-  # We don't have a dedicated non-editable show view
  def show
-    edit
+    respond_to do |format|
+        # We don't have a dedicated non-editable show view
+      format.html { edit }
+      format.json do
+        if (case_log = CaseLog.find_by(id: params[:id]))
+          render json: case_log, status: :ok
+        else
+          render json: { error: "Case Log #{params[:id]} not found" }, status: :not_found
+        end
+      end
+    end
  end

  def edit
@ -90,7 +99,7 @@ class CaseLogsController < ApplicationController

 private

-  API_ACTIONS = %w[create update destroy].freeze
+  API_ACTIONS = %w[create show update destroy].freeze

  def question_responses(questions_for_page)
    questions_for_page.each_with_object({}) do |(question_key, question_info), result|
--- a/config/forms/2021_2022.json
+++ b/config/forms/2021_2022.json
@ -31,7 +31,7 @@
                  "hint_text": "",
                  "type": "numeric",
                  "min": 0,
-                  "max": 150,
+                  "max": 120,
                  "step": 1
                }
              }
--- a/docs/adr/adr-001-initial-architecture-decisions.md
+++ b/docs/adr/adr-001-initial-architecture-decisions.md
--- a/docs/adr/adr-002-repositories.md
+++ b/docs/adr/adr-002-repositories.md
--- a/docs/adr/adr-003-form-submission-flow.md
+++ b/docs/adr/adr-003-form-submission-flow.md
--- a/docs/adr/adr-004-gov-paas.md
+++ b/docs/adr/adr-004-gov-paas.md
--- a/docs/adr/adr-005-form-definition.md
+++ b/docs/adr/adr-005-form-definition.md
--- a/docs/adr/adr-006-saving-values.md
+++ b/docs/adr/adr-006-saving-values.md
--- a/docs/adr/adr-007-data-validations.md
+++ b/docs/adr/adr-007-data-validations.md
--- a/docs/api/DLUHC-CORE-Data.v1.json
+++ b/docs/api/DLUHC-CORE-Data.v1.json
--- a/docs/index.html
+++ b/docs/index.html
@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="stylesheet" type="text/css" href="//pagecdn.io/lib/swagger-ui/v3.31.1/swagger-ui.css">
+<title>OpenAPI DLUHC CORE Data Collection</title>
+<body><div id="openapi"><script src="//pagecdn.io/lib/swagger-ui/v3.31.1/swagger-ui-bundle.js"></script>
+<script>
+window.onload = function () {
+  const ui = SwaggerUIBundle({
+    url: "api/DLUHC-CORE-Data.v1.json",
+    dom_id: "#openapi"
+  })
+}
+</script>
+</body>
--- a/spec/requests/case_log_controller_spec.rb
+++ b/spec/requests/case_log_controller_spec.rb
@ -99,6 +99,24 @@ RSpec.describe CaseLogsController, type: :request do
    end
  end

+  describe "GET" do
+    let(:case_log) { FactoryBot.create(:case_log, :completed) }
+    let(:id) { case_log.id }
+
+    before do
+      get "/case_logs/#{id}", headers: headers
+    end
+
+    it "returns http success" do
+      expect(response).to have_http_status(:success)
+    end
+
+    it "returns a serialized Case Log" do
+      json_response = JSON.parse(response.body)
+      expect(json_response["status"]).to eq(case_log.status)
+    end
+  end
+
  describe "PATCH" do
    let(:case_log) do
      FactoryBot.create(:case_log, :in_progress, tenant_code: "Old Value", property_postcode: "Old Value")