docs(FCL-283): Further improvements and clarifications to the OpenAPI…

… spec

doc/openapi/public_api.yml

@@ -11,6 +11,18 @@ info:
     - Case Name
     - Party Names
     - Judges' Names
+
+    ## Detecting content changes
+
+    Whenever a judgment gets changed it appears in the recently published list. This includes minor updates such as when we enrich the document with hyperlinks to other legal citations, as well as more significant changes such as revisions we have received from the courts.
+
+    Both the Atom feed and the judgment XML include a content hash so that you can check if the text of the document has changed.
+
+    ## Give us your feedback
+
+    We are still actively developing Find Case Law based on user feedback. This includes improving the experience of how data re-users can access the data.
+
+    You can provide feedback by using our [feedback form](https://corexmsnp4n42lf2kht3.qualtrics.com/jfe/form/SV_0lyyYAzfv9bGcyW).
   termsOfService: "https://caselaw.nationalarchives.gov.uk/terms-of-use"
   contact:
     email: [email protected]
@@ -23,18 +35,16 @@ info:
 servers:
   - url: "https://caselaw.nationalarchives.gov.uk"
     description: ""
-tags:
-  - name: Reading
-    description: Operations for reading document content and metadata
 components:
   parameters:
-    judgmentUri:
-      name: judgmentUri
+    documentUri:
+      name: document_uri
       in: path
       required: true
       schema:
         type: string
       example: ewhc/tcc/2022/42
+      description: The unique identifier for this document within Find Case Law.
   responses:
     judgmentFeed:
       description: An Atom feed of recently published judgments
@@ -43,7 +53,7 @@ components:
           schema:
             description: List in Atom
     judgment:
-      description: "A single judgment document, in Akoma Ntoso XML"
+      description: "The contents of a single document, as [Akoma Ntoso XML](https://www.oasis-open.org/standard/akn-v1-0/)."
       content:
         application/akn+xml:
           schema:
@@ -52,12 +62,12 @@ components:
 paths:
   "/{court}/{subdivision}/{year}/atom.xml":
     get:
-      summary: Get recently published or updated judgments
+      summary: Get a list of recently published or updated documents
       description: |
-        Less specific feeds can be gained by omitting the components e.g. /, /2022/, /ewhc/ and /ewhc/ch/ are all valid prefixes to atom.xml Note that a {court} is required if there is a {subdivision}
+        Less specific feeds can be gained by omitting the components e.g. `/`, `/2022/`, `/ewhc/` and `/ewhc/ch/` are all valid prefixes to `atom.xml`.
+
+        Note that a `{court}` is required if there is a `{subdivision}`.
       operationId: listJudgments
-      tags:
-        - Reading
       parameters:
         - name: order
           required: false
@@ -72,12 +82,20 @@ paths:
               - transformation
               - "-transformation"
             default: "-date"
+            description: |
+              Which of the dates within the document to use for ordering. Prepend a `-` to sort by newest first.
+
+              - `date`: The date the document was first published by the court
+              - `updated`: The last date the document was updated in the Find Case Law system, including changes to its metadata
+              - `transformation`: The date the body of the document was last modified, including changes to either the body text, XML markup, or both
         - name: page
           required: false
           in: query
           schema:
             type: integer
             default: 1
+            minimum: 1
+          description: "Where results are across multiple pages, the page of results to return."
       responses:
         "200":
           $ref: "#/components/responses/judgmentFeed"
@@ -100,14 +118,14 @@ paths:
         example: 2022
         schema:
           type: integer
-  "/{judgmentUri}/data.xml":
+  "/{document_uri}/data.xml":
     get:
-      summary: "Read a published judgment or decision, given its URI"
+      summary: "Get a single document"
       operationId: getDocumentByUri
-      tags:
-        - Reading
       responses:
         "200":
           $ref: "#/components/responses/judgment"
+      x-stoplight:
+        id: hfo3m1wc3ben3
     parameters:
-      - $ref: "#/components/parameters/judgmentUri"
+      - $ref: "#/components/parameters/documentUri"