From 15a9f467c0cbd6b9b7c28f9d1a2ff77cbff6e706 Mon Sep 17 00:00:00 2001
From: Stevan Freeborn <65925598+StevanFreeborn@users.noreply.github.com>
Date: Thu, 13 Apr 2023 17:22:28 -0500
Subject: [PATCH] docs: add more documentation

---
 src/app/components/NavBar.tsx                 | 16 +++--
 src/app/components/Section.module.css         |  8 +++
 src/app/types/types.ts                        |  1 +
 src/docs/version_001/docsStructure.ts         |  1 +
 .../version_002/authentication/example.md     |  2 +-
 src/docs/version_002/docsStructure.ts         |  8 +++
 src/docs/version_002/introduction/copy.md     |  2 +
 src/docs/version_002/introduction/example.md  |  8 +++
 src/docs/version_002/pagination/copy.md       | 71 +++++++++++++++++++
 src/docs/version_002/pagination/example.md    | 15 ++++
 .../resources/records/field_values/copy.md    | 12 ++--
 .../resources/records/field_values/example.md |  2 +
 12 files changed, 132 insertions(+), 14 deletions(-)
 create mode 100644 src/docs/version_002/pagination/copy.md
 create mode 100644 src/docs/version_002/pagination/example.md

diff --git a/src/app/components/NavBar.tsx b/src/app/components/NavBar.tsx
index 6201e8c..00bded7 100644
--- a/src/app/components/NavBar.tsx
+++ b/src/app/components/NavBar.tsx
@@ -101,13 +101,15 @@ export default function NavBar({
           <NavbarDropdown version={version.version} />
         </li>
         <li className={styles.navItem}>
-          <Link
-            href="https://api.onspring.com/swagger"
-            className={styles.navLink}
-            target="_blank"
-          >
-            Swagger
-          </Link>
+          {version.hasSwagger ? (
+            <Link
+              href="https://api.onspring.com/swagger"
+              className={styles.navLink}
+              target="_blank"
+            >
+              Swagger
+            </Link>
+          ) : null}
         </li>
         <li className={styles.navItem}>
           <Link
diff --git a/src/app/components/Section.module.css b/src/app/components/Section.module.css
index bdfd6f6..258a254 100644
--- a/src/app/components/Section.module.css
+++ b/src/app/components/Section.module.css
@@ -78,4 +78,12 @@
   text-decoration: none;
   color: #64adac;
   font-weight: bold;
+}
+
+.container ul {
+  padding: 0;
+  margin: 0;
+  list-style: circle;
+  margin-top: 1rem;
+  margin-left: 1rem;
 }
\ No newline at end of file
diff --git a/src/app/types/types.ts b/src/app/types/types.ts
index b28ecc0..38e3f0e 100644
--- a/src/app/types/types.ts
+++ b/src/app/types/types.ts
@@ -2,6 +2,7 @@ import { ReactNode } from 'react';
 
 export type DocsStructure = {
   version: string;
+  hasSwagger: boolean;
   docs: Doc[];
 };
 
diff --git a/src/docs/version_001/docsStructure.ts b/src/docs/version_001/docsStructure.ts
index 706f36c..af0aa72 100644
--- a/src/docs/version_001/docsStructure.ts
+++ b/src/docs/version_001/docsStructure.ts
@@ -2,6 +2,7 @@ import { DocsStructure } from '@/app/types/types';
 
 export const versionOne: DocsStructure = {
   version: 'version_001',
+  hasSwagger: false,
   docs: [
     {
       title: 'Introduction',
diff --git a/src/docs/version_002/authentication/example.md b/src/docs/version_002/authentication/example.md
index 86559cf..d24c56d 100644
--- a/src/docs/version_002/authentication/example.md
+++ b/src/docs/version_002/authentication/example.md
@@ -2,7 +2,7 @@
 
 API Keys are specific to an instance. If you are using the API to access data from multiple instances, you will need to create an API key for each instance.
 
-{% code heading="X-API KEY" defaultLanguage="text" %}
+{% code heading="X-APIKEY" defaultLanguage="text" %}
 
 ```text
 X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000
diff --git a/src/docs/version_002/docsStructure.ts b/src/docs/version_002/docsStructure.ts
index 6394613..f8263f1 100644
--- a/src/docs/version_002/docsStructure.ts
+++ b/src/docs/version_002/docsStructure.ts
@@ -2,6 +2,7 @@ import { DocsStructure } from '@/app/types/types';
 
 export const versionTwo: DocsStructure = {
   version: 'version_002',
+  hasSwagger: true,
   docs: [
     {
       title: 'Introduction',
@@ -17,6 +18,13 @@ export const versionTwo: DocsStructure = {
       example: 'example.md',
       children: [],
     },
+    {
+      title: 'Pagination',
+      folder: 'pagination',
+      copy: 'copy.md',
+      example: 'example.md',
+      children: [],
+    },
     {
       title: 'Resources',
       folder: 'resources',
diff --git a/src/docs/version_002/introduction/copy.md b/src/docs/version_002/introduction/copy.md
index 1afafc7..5fee734 100644
--- a/src/docs/version_002/introduction/copy.md
+++ b/src/docs/version_002/introduction/copy.md
@@ -3,3 +3,5 @@
 The Onspring API is organized around REST. It enables external programs to retrieve, save, and delete data within your Onspring instance. The Onspring API implements version 3 of the Open API Specification (OAS).
 
 The Onspring API does support bulk operation for some, but not all endpoints. Bulk operations are not supported for endpoints that create, update, or delete resources. The one exception is the batch delete endpoint for records, which is used to delete multiple records at once.
+
+You can specify the version of the API that you want to use by including the version number in the `x-api-version` header. If you do not specify a version number the API will attempt to route the request to the proper version based upon the request path.
diff --git a/src/docs/version_002/introduction/example.md b/src/docs/version_002/introduction/example.md
index 2b83cef..e92004c 100644
--- a/src/docs/version_002/introduction/example.md
+++ b/src/docs/version_002/introduction/example.md
@@ -9,3 +9,11 @@ https://api.onspring.com
 ```
 
 {% /code %}
+
+{% code heading="X-API-VERSION" defaultLanguage="text" %}
+
+```text
+X-Api-Version: 2
+```
+
+{% /code %}
diff --git a/src/docs/version_002/pagination/copy.md b/src/docs/version_002/pagination/copy.md
new file mode 100644
index 0000000..55d3226
--- /dev/null
+++ b/src/docs/version_002/pagination/copy.md
@@ -0,0 +1,71 @@
+# Pagination {% #pagination %}
+
+The Onspring API supports pagination for some endpoints for some resources. Pagination is used to limit the number of objects returned in a single response. This is useful for reducing the amount of data transferred over the network and for reducing the amount of data that needs to be processed by the client. If you are attempting to retrieve a large number of objects via one of the following endpoints you will need to use pagination to retrieve all of the them. The following endpoints support pagination:
+
+- [Get Fields by App](#get-fields-by-app)
+- [Get Records by App](#get-records-by-app)
+- [Get Records by Query](#get-records-by-query)
+- [Get Reports by App](#get-reports-by-app)
+
+## Pagination Query Parameters {% #pagination-parameters %}
+
+When making a request to one of the endpoints that support pagination you can use the following parameters to control the pagination behavior:
+
+{% table .propertiesTable %}
+
+- Parameter Name
+- Description
+
+---
+
+- PageNumber
+- The page number to retrieve. The default value is `1`.
+
+---
+
+- PageSize
+- The number of objects to retrieve per page. The default value is `50`. The maximum value is `1000`.
+
+{% /table %}
+
+## Pagination Response {% #pagination-response %}
+
+When making a request to one of the endpoints that support pagination you will receive a response that contains a `Paged Collection` object that has the following properties which can be used to determine if there are more pages of data available and to retrieve the next page of data:
+
+{% table .propertiesTable %}
+
+- Property Name
+- Data Type
+- Description
+
+---
+
+- pageNumber
+- `number`
+- The page number of the current page of data.
+
+---
+
+- pageSize
+- `number`
+- The number of objects per page.
+
+---
+
+- totalPages
+- `number`
+- The total number of pages of data available.
+
+---
+
+- totalRecords
+- `number`
+- The total number of objects available.
+
+---
+
+- items
+- `object[]`
+- The array of objects for the current page.
+
+{% /table %}
diff --git a/src/docs/version_002/pagination/example.md b/src/docs/version_002/pagination/example.md
new file mode 100644
index 0000000..88ed4ee
--- /dev/null
+++ b/src/docs/version_002/pagination/example.md
@@ -0,0 +1,15 @@
+# The Paged Collection Object
+
+{% code heading="PAGED COLLECTION" defaultLanguage="json" %}
+
+```json
+{
+  "pageNumber": 1,
+  "pageSize": 1,
+  "totalPages": 1,
+  "totalRecords": 1,
+  "items": []
+}
+```
+
+{% /code %}
diff --git a/src/docs/version_002/resources/records/field_values/copy.md b/src/docs/version_002/resources/records/field_values/copy.md
index 196fa85..f30d828 100644
--- a/src/docs/version_002/resources/records/field_values/copy.md
+++ b/src/docs/version_002/resources/records/field_values/copy.md
@@ -65,7 +65,7 @@ These are objects representing a field value in a record. They will comprise the
 ---
 
 - TimeSpan
-- A [Time Span](#time-span-value) value.
+- A [Time Span](#time-span-field-value) value.
 - `object`
 
 ---
@@ -95,13 +95,13 @@ These are objects representing a field value in a record. They will comprise the
 ---
 
 - AttachmentList
-- A list of [Attachment](#attachment-value) values.
+- A list of [Attachment](#attachment-field-value) values.
 - `object[]`
 
 ---
 
 - ScoringGroupList
-- A list of [Scoring Group](#scoring-group-value) values.
+- A list of [Scoring Group](#scoring-group-field-value) values.
 - `object[]`
 
 ---
@@ -112,7 +112,7 @@ These are objects representing a field value in a record. They will comprise the
 
 {% /table %}
 
-### Time Span Value {% #time-span-value %}
+### Time Span Field Value {% #time-field-span-value %}
 
 {% table .propertiesTable %}
 
@@ -152,7 +152,7 @@ These are objects representing a field value in a record. They will comprise the
 
 {% /table %}
 
-### Attachment Value {% #attachment-value %}
+### Attachment Field Value {% #attachment-field-value %}
 
 {% table .propertiesTable %}
 
@@ -186,7 +186,7 @@ These are objects representing a field value in a record. They will comprise the
 
 {% /table %}
 
-### Scoring Group Value {% #scoring-group-value %}
+### Scoring Group Field Value {% #scoring-group-field-value %}
 
 {% table .propertiesTable %}
 
diff --git a/src/docs/version_002/resources/records/field_values/example.md b/src/docs/version_002/resources/records/field_values/example.md
index 9fb47b6..7653770 100644
--- a/src/docs/version_002/resources/records/field_values/example.md
+++ b/src/docs/version_002/resources/records/field_values/example.md
@@ -1,5 +1,7 @@
 # The Field Value Object
 
+The following snippet contains an example of field value objects for each of the possible field value types.
+
 {% code heading="FIELD VALUES" defaultLanguage="json" %}
 
 ```json