Adds new REST API page layout with JSON Editor

* Add the JSONEditor package to package.json * Create a rest_api.erb layout for hosting REST API documentation - it hosts a JSONEditor that is initialized on any page that contains the expected data * Define new frontmatter for REST API pages that populate the rest_api.erb layout * Make it possible to load a full JSON response into a REST API doc page * Convert a few pages to the new format
OneBusAway · Mar 20, 2024 · afd63d9 · afd63d9
1 parent 5b5a9d4
commit afd63d9
Show file tree

Hide file tree

Showing 16 changed files with 399 additions and 99 deletions.
diff --git a/frontend/javascript/code_snippets.js b/frontend/javascript/code_snippets.js
@@ -1,3 +1,5 @@
+import JSONEditor from "jsoneditor";
+
 export function enableCodeHighlighting() {
   document.querySelectorAll('pre code').forEach(block => block.textContent = block.textContent.trim());
   hljs.highlightAll();
@@ -79,4 +81,26 @@ export function insertCodeSnippetCopyButtons() {
     });
   });
 }
-
+
+export function initializeJSONEditor() {
+  // Does the page have JSON data?
+  const jsonTextElt = document.getElementById("json-data");
+  if (!jsonTextElt) {
+    return;
+  }
+
+  // Can we turn it into a JS object?
+  const jsonData = JSON.parse(jsonTextElt.innerText);
+  if (!jsonData) {
+    return;
+  }
+
+  // create the editor
+  const container = document.getElementById("json-editor");
+  const options = {
+    mode: 'code',
+    modes: ['code', 'view'], // allowed modes
+  }
+  const editor = new JSONEditor(container, options);
+  editor.set(jsonData);
+}
diff --git a/frontend/javascript/index.js b/frontend/javascript/index.js
@@ -1,10 +1,12 @@
-import "$styles/index.css"
-import "$styles/syntax-highlighting.css"
+import "$styles/index.css";
+import "$styles/syntax-highlighting.css";
+import "jsoneditor/dist/jsoneditor.min.css";
 
 import {
   enableCodeHighlighting,
   insertCodeSnippetCopyButtons,
-  copyHeadingDirectLinks
+  copyHeadingDirectLinks,
+  initializeJSONEditor,
 } from "./code_snippets";
 
 import {
@@ -24,6 +26,7 @@ document.addEventListener("DOMContentLoaded", function(event) {
   copyHeadingDirectLinks();
   enableCodeHighlighting();
   insertCodeSnippetCopyButtons();
+  initializeJSONEditor();
   enableDocSearch('#oba-docs-search-container--desktop');
   enableDocSearch('#oba-docs-search-container--mobile');
   enableScrollToTop();

diff --git a/frontend/styles/index.css b/frontend/styles/index.css
@@ -58,4 +58,13 @@ pre.highlight {
   padding: 0!important;
 }
 
+.jsoneditor {
+  @apply !border-zinc-300;
+}
+
+.jsoneditor-menu {
+  @apply bg-gradient-to-br;
+  @apply from-green-600 to-green-700;
+}
+
 @tailwind utilities;
diff --git a/package.json b/package.json
@@ -17,5 +17,8 @@
     "postcss-preset-env": "^9.1.2",
     "read-cache": "^1.0.0",
     "tailwindcss": "^3.4.1"
+  },
+  "dependencies": {
+    "jsoneditor": "^10.0.2"
   }
 }
diff --git a/src/_layouts/default.erb b/src/_layouts/default.erb
@@ -26,9 +26,8 @@
         <div class="relative flex h-full flex-col px-4 pt-14 sm:px-6 lg:px-8">
           <main class="flex-auto">
             <article class="flex h-full flex-col pb-10 pt-16">
-              <div class="flex-auto prose dark:prose-invert break-words [html_:where(&>*)]:mx-auto [html_:where(&>*)]:max-w-2xl [html_:where(&>*)]:lg:mx-[calc(50%-min(50%,theme(maxWidth.lg)))] [html_:where(&>*)]:lg:max-w-3xl">
+              <div class="flex-auto [html_:where(&>*)]:mx-auto [html_:where(&>*)]:max-w-2xl [html_:where(&>*)]:lg:mx-[calc(50%-min(50%,theme(maxWidth.lg)))] [html_:where(&>*)]:lg:max-w-3xl">
                 <%= render "bg_checkerboard" %>
-                <h1><%= data.title %></h1>
                 <%= content %>
               </div>
             </article>

diff --git a/src/_layouts/page.erb b/src/_layouts/page.erb
@@ -2,4 +2,7 @@
 layout: default
 ---
 
-<%= content %>
+<div class="prose dark:prose-invert break-words">
+  <h1><%= data.title %></h1>
+  <%= content %>
+</div>
diff --git a/src/_layouts/post.erb b/src/_layouts/post.erb
@@ -2,6 +2,8 @@
 layout: default
 ---
 
-<h1><%= data.title %></h1>
+<div class="prose dark:prose-invert break-words">
+  <h1><%= data.title %></h1>
 
-<%= content %>
+  <%= content %>
+</div>
diff --git a/src/_layouts/rest_api.erb b/src/_layouts/rest_api.erb
@@ -0,0 +1,23 @@
+---
+layout: default
+---
+
+<div class="prose dark:prose-invert break-words">
+  <h1><%= data.title %></h1>
+  <p><%= data.description %></p>
+  <h2>Example Request</h2>
+  <p>
+    <a href="<%= data.sample_request_url %>">
+      <%= data.sample_request_url %>
+    </a>
+  </p>
+
+  <% if data.example_response_file %>
+    <h2>Example Response</h2>
+    <div id="json-data" class='hidden'><%= File.open(File.join(site.root_dir, "src/api/example_responses/", data.example_response_file)).read %></div>
+    <div class='not-prose'>
+      <div id="json-editor" style="height:500px"></div>
+    </div>
+  <% end %>
+  <%= content %>
+</div>
diff --git a/src/api/example_responses/agencies-with-coverage.json b/src/api/example_responses/agencies-with-coverage.json
@@ -0,0 +1,210 @@
+{
+  "code": 200,
+  "currentTime": 1710953797130,
+  "data": {
+    "limitExceeded": false,
+    "list": [
+      {
+        "agencyId": "1",
+        "lat": 47.53009,
+        "latSpan": 0.6819459999999964,
+        "lon": -122.1462285,
+        "lonSpan": 0.7207869999999872
+      },
+      {
+        "agencyId": "23",
+        "lat": 47.613395499999996,
+        "latSpan": 0.02854099999999704,
+        "lon": -122.3263055,
+        "lonSpan": 0.024529000000001133
+      },
+      {
+        "agencyId": "3",
+        "lat": 47.230847499999996,
+        "latSpan": 0.31803900000000596,
+        "lon": -122.4183365,
+        "lonSpan": 0.4140730000000019
+      },
+      {
+        "agencyId": "29",
+        "lat": 47.9386755,
+        "latSpan": 0.6797269999999997,
+        "lon": -121.99285549999999,
+        "lonSpan": 0.7837090000000018
+      },
+      {
+        "agencyId": "19",
+        "lat": 47.0469795,
+        "latSpan": 0.2278790000000015,
+        "lon": -122.730118,
+        "lonSpan": 0.49401799999999696
+      },
+      {
+        "agencyId": "95",
+        "lat": 47.951749,
+        "latSpan": 1.2923619999999971,
+        "lon": -122.6595315,
+        "lonSpan": 0.7104370000000131
+      },
+      {
+        "agencyId": "40",
+        "lat": 47.5346645,
+        "latSpan": 0.8893070000000023,
+        "lon": -122.32945649999999,
+        "lonSpan": 0.6211330000000004
+      },
+      {
+        "agencyId": "96",
+        "lat": 47.616654499999996,
+        "latSpan": 0.009216999999999587,
+        "lon": -122.3434575,
+        "lonSpan": 0.012994999999989432
+      },
+      {
+        "agencyId": "97",
+        "lat": 47.9448935,
+        "latSpan": 0.12988500000000158,
+        "lon": -122.24544,
+        "lonSpan": 0.12188199999999938
+      },
+      {
+        "agencyId": "20",
+        "lat": 47.640299999999996,
+        "latSpan": 0.3441580000000002,
+        "lon": -122.524309,
+        "lonSpan": 0.3730040000000088
+      }
+    ],
+    "references": {
+      "agencies": [
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "https://kingcounty.gov/en/dept/metro/fares-and-payment/prices",
+          "id": "1",
+          "lang": "EN",
+          "name": "Metro Transit",
+          "phone": "206-553-3000",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://kingcounty.gov/en/dept/metro"
+        },
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "https://www.seattle.gov/transportation/getting-around/transit/streetcar/fares-and-orca-card",
+          "id": "23",
+          "lang": "EN",
+          "name": "City of Seattle",
+          "phone": "206-684-7623",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.seattle.gov/transportation/getting-around/transit/streetcar"
+        },
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "https://www.piercetransit.org/PT-fares/",
+          "id": "3",
+          "lang": "en",
+          "name": "Pierce Transit",
+          "phone": "1-253-581-8000",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.piercetransit.org"
+        },
+        {
+          "disclaimer": "",
+          "email": "riders@commtrans.org",
+          "fareUrl": "https://www.communitytransit.org/fares-and-passes",
+          "id": "29",
+          "lang": "en",
+          "name": "Community Transit",
+          "phone": "(800) 562-1375",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.communitytransit.org/"
+        },
+        {
+          "disclaimer": "",
+          "email": "customerservice@intercitytransit.com",
+          "fareUrl": "https://www.intercitytransit.com/zerofare-faqs",
+          "id": "19",
+          "lang": "en",
+          "name": "Intercity Transit",
+          "phone": "360-786-1881",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.intercitytransit.com/"
+        },
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "https://wave2go.wsdot.com/webstore/landingPage?cg=21&c=76",
+          "id": "95",
+          "lang": "en",
+          "name": "Washington State Ferries",
+          "phone": "1 (888) 808-7977",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.wsdot.wa.gov/ferries/"
+        },
+        {
+          "disclaimer": "",
+          "email": "main@soundtransit.org",
+          "fareUrl": "https://www.soundtransit.org/ride-with-us/how-to-pay/fares",
+          "id": "40",
+          "lang": "en",
+          "name": "Sound Transit",
+          "phone": "1-888-889-6368",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "https://www.soundtransit.org"
+        },
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "",
+          "id": "96",
+          "lang": "en",
+          "name": "Seattle Center Monorail",
+          "phone": "2069052620",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "http://www.seattlemonorail.com"
+        },
+        {
+          "disclaimer": "",
+          "email": "",
+          "fareUrl": "http://www.everetttransit.org/",
+          "id": "97",
+          "lang": "en",
+          "name": "Everett Transit",
+          "phone": "",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "http://www.everetttransit.org/"
+        },
+        {
+          "disclaimer": "",
+          "email": "kitsapride@kitsaptransit.com",
+          "fareUrl": "http://www.kitsaptransit.com/fares/fares",
+          "id": "20",
+          "lang": "en",
+          "name": "Kitsap Transit",
+          "phone": "(800) 501-7433",
+          "privateService": false,
+          "timezone": "America/Los_Angeles",
+          "url": "http://www.kitsaptransit.com"
+        }
+      ],
+      "routes": [],
+      "situations": [],
+      "stopTimes": [],
+      "stops": [],
+      "trips": []
+    }
+  },
+  "text": "OK",
+  "version": 2
+}
diff --git a/src/api/example_responses/agency-1.json b/src/api/example_responses/agency-1.json
@@ -0,0 +1 @@
+{"code":200,"currentTime":1710959263486,"data":{"entry":{"disclaimer":"","email":"","fareUrl":"https://kingcounty.gov/en/dept/metro/fares-and-payment/prices","id":"1","lang":"EN","name":"Metro Transit","phone":"206-553-3000","privateService":false,"timezone":"America/Los_Angeles","url":"https://kingcounty.gov/en/dept/metro"},"references":{"agencies":[],"routes":[],"situations":[],"stopTimes":[],"stops":[],"trips":[]}},"text":"OK","version":2}
diff --git a/src/api/example_responses/arrivals-and-departures-for-stop-1_75403.json b/src/api/example_responses/arrivals-and-departures-for-stop-1_75403.json
diff --git a/src/api/where/methods/agencies-with-coverage.md b/src/api/where/methods/agencies-with-coverage.md
@@ -1,37 +1,11 @@
 ---
-layout: page
+layout: rest_api
 title: agency-with-coverage Method
+description: Returns a list of all transit agencies currently supported by OneBusAway along with the center of their coverage area.
+sample_request_url: https://api.pugetsound.onebusaway.org/api/where/agencies-with-coverage.json?key=TEST
+example_response_file: agencies-with-coverage.json
 ---
 
-Returns a list of all transit agencies currently supported by OneBusAway along with the center of their coverage area.
-
-## Sample Request
-
-[http://api.pugetsound.onebusaway.org/api/where/agencies-with-coverage.json?key=TEST](http://api.pugetsound.onebusaway.org/api/where/agencies-with-coverage.json?key=TEST)
-
-## Sample Response
-
-    <response>
-      <version>2</version>
-      <code>200</code>
-      <text>OK</text>
-      <currentTime>1270614730908</currentTime>
-      <data class="listWithReferences">
-        <references>...</references>
-        <list>
-          <agencyWithCoverage>
-            <agencyId>3</agencyId>
-            <lat>47.21278384769539</lat>
-            <lon>-122.45624875362905</lon>
-            <latSpan>0.3559410000000014</latSpan>
-            <lonSpan>0.9080050000000028</lonSpan>
-          </agencyWithCoverage>
-          <agencyWithCoverage>...</agencyWithCoverage>
-       </list>
-        <limitExceeded>false</limitExceeded>
-      </data>
-    </response>
-
 ## Response
 
 The response has the following fields:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{"code":200,"currentTime":1710959263486,"data":{"entry":{"disclaimer":"","email":"","fareUrl":"https://kingcounty.gov/en/dept/metro/fares-and-payment/prices","id":"1","lang":"EN","name":"Metro Transit","phone":"206-553-3000","privateService":false,"timezone":"America/Los_Angeles","url":"https://kingcounty.gov/en/dept/metro"},"references":{"agencies":[],"routes":[],"situations":[],"stopTimes":[],"stops":[],"trips":[]}},"text":"OK","version":2}