From 6abd616026516c28297fb6f58631bdf143cab24a Mon Sep 17 00:00:00 2001 From: Andy Clifford Date: Mon, 9 Oct 2023 15:08:17 +1300 Subject: [PATCH] Endpoint component with markdoc This change allows us to document api endpoints using markdoc using the same layout as seen in the [Protocol Tailwind UI Example](https://protocol.tailwindui.com/contacts#list-all-contacts). There are issues with the styling such as the h2 header but we are just focussed on getting the layout correct then will followup with styling later once we have aligned with the designers. --- markdoc.config.mjs | 29 +++++++- package.json | 4 +- .../links.integration.test.js.snap | 1 + src/components/Code.astro | 7 ++ src/components/Column.astro | 8 ++ src/components/Endpoint.astro | 28 +++++++ src/components/Row.astro | 3 + src/content/api/media-uploads.mdoc | 74 +++++++++++++++++++ 8 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 src/components/Code.astro create mode 100644 src/components/Column.astro create mode 100644 src/components/Endpoint.astro create mode 100644 src/components/Row.astro diff --git a/markdoc.config.mjs b/markdoc.config.mjs index d8fe70c10..05e326a07 100644 --- a/markdoc.config.mjs +++ b/markdoc.config.mjs @@ -1,6 +1,14 @@ import { defineMarkdocConfig, component } from '@astrojs/markdoc/config'; +import shiki from '@astrojs/markdoc/shiki'; export default defineMarkdocConfig({ + extends: [ + shiki({ + theme: 'github-light', + wrap: true, + langs: [], + }), + ], tags: { properties: { render: component('./src/components/Properties.astro'), @@ -11,6 +19,25 @@ export default defineMarkdocConfig({ name: { type: String, required: true }, type: { type: String, required: true }, }, - } + }, + endpoint: { + render: component('./src/components/Endpoint.astro'), + attributes: { + method: { type: String, required: true }, + path: { type: String, required: true }, + }, + }, + row: { + render: component('./src/components/Row.astro'), + }, + column: { + render: component('./src/components/Column.astro'), + attributes: { + sticky: { type: Boolean }, + }, + }, + code: { + render: component('./src/components/Code.astro'), + }, } }); diff --git a/package.json b/package.json index 29dcd9441..b1ed1e0fc 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ "flexsearch": "^0.7.31", "glob": "^8.1.0", "gray-matter": "^4.0.3", + "jsdom": "^22.1.0", "linkinator": "^5.0.2", "mdast-util-to-string": "^3.1.1", "mermaid": "^9.3.0", @@ -43,7 +44,6 @@ "unist-util-find-after": "^4.0.1", "unist-util-visit": "^4.1.2", "vitest": "^0.28.3", - "vue": "^3.2.47", - "jsdom": "^22.1.0" + "vue": "^3.2.47" } } diff --git a/src/__tests__/__snapshots__/links.integration.test.js.snap b/src/__tests__/__snapshots__/links.integration.test.js.snap index ed1d51a25..5040d8d49 100644 --- a/src/__tests__/__snapshots__/links.integration.test.js.snap +++ b/src/__tests__/__snapshots__/links.integration.test.js.snap @@ -302,6 +302,7 @@ exports[`the build should not break any links 1`] = ` "/api/managed-integrations#paypal-referral", "/api/managed-integrations#top", "/api/media-uploads", + "/api/media-uploads#attributes", "/api/media-uploads#contents", "/api/media-uploads#create-a-presigned-url-for-media-upload-experimental", "/api/media-uploads#get-media-upload-location-experimental", diff --git a/src/components/Code.astro b/src/components/Code.astro new file mode 100644 index 000000000..9b3a660fb --- /dev/null +++ b/src/components/Code.astro @@ -0,0 +1,7 @@ +--- +import ProseCode from "./ProseCode.vue"; +--- + + + + diff --git a/src/components/Column.astro b/src/components/Column.astro new file mode 100644 index 000000000..7eb86336b --- /dev/null +++ b/src/components/Column.astro @@ -0,0 +1,8 @@ + +--- +const { sticky = false } = Astro.props; +--- + +
:first-child]:mt-0 [&>:last-child]:mb-0 xl:sticky xl:top-24' : '[&>:first-child]:mt-0 [&>:last-child]:mb-0'}`> + +
diff --git a/src/components/Endpoint.astro b/src/components/Endpoint.astro new file mode 100644 index 000000000..7945e2166 --- /dev/null +++ b/src/components/Endpoint.astro @@ -0,0 +1,28 @@ + +--- +const { method, path } = Astro.props; +const valueColorMap = { + GET: 'emerald', + POST: 'sky', + PUT: 'amber', + DELETE: 'rose', +}; +const color = valueColorMap[method] || 'emerald'; +const colorStyles = { + emerald: 'ring-emerald-300 dark:ring-emerald-400/30 bg-emerald-400/10 text-emerald-500 dark:text-emerald-400', + sky: 'ring-sky-300 bg-sky-400/10 text-sky-500 dark:ring-sky-400/30 dark:bg-sky-400/10 dark:text-sky-400', + amber: 'ring-amber-300 bg-amber-400/10 text-amber-500 dark:ring-amber-400/30 dark:bg-amber-400/10 dark:text-amber-400', + rose: 'ring-rose-200 bg-rose-50 text-red-500 dark:ring-rose-500/20 dark:bg-rose-400/10 dark:text-rose-400', +} +--- + +
+
+ { method } + + { path } +
+ + + +
diff --git a/src/components/Row.astro b/src/components/Row.astro new file mode 100644 index 000000000..46978294c --- /dev/null +++ b/src/components/Row.astro @@ -0,0 +1,3 @@ +
+ +
diff --git a/src/content/api/media-uploads.mdoc b/src/content/api/media-uploads.mdoc index ec7ada107..ba8e0c33c 100644 --- a/src/content/api/media-uploads.mdoc +++ b/src/content/api/media-uploads.mdoc @@ -44,3 +44,77 @@ When the Media Upload was updated. The User or API Key that updated the Media Upload. {% /property %} {% /properties %} + +{% endpoint method="POST" path="/api/media-uploads" %} +## Create a presigned URL for Media Upload EXPERIMENTAL +{% row %} +{% column %} +### Attributes +{% properties %} +{% property name="accountId" type="string" %} +The Media Upload's owning Centrapay Account id. +{% /property %} + +{% property name="mimeType" type="string" %} +The media (MIME) type of the upload. +{% /property %} + +{% property name="fileName" type="string" %} +The file name of the upload. +{% /property %} +{% /properties %} +{% /column %} + +{% column sticky=true %} + +{% code %} +```bash +curl -X POST https://service.centrapay.com/api/media-uploads \ + -H "X-Api-Key: $api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "accountId": "Jaim1Cu1Q55uooxSens6yk", + "mimeType": "image/png", + "fileName": "image.png" + }' +``` +{% /code %} + +{% code %} +```json +{ + "id": "DKTs3U38hdhfEqwF1JKoT2", + "uploadUrl": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743" +} +``` +{% /code %} + +{% /column %} +{% /row %} +{% /endpoint %} + + +{% endpoint method="GET" path="/api/media-uploads/{mediaUploadId}/location" %} +## Get Media Upload Location EXPERIMENTAL +{% row %} +{% column/ %} +{% column sticky=true %} + +{% code %} +```bash +curl https://service.centrapay.com/api/media-uploads/DKTs3U38hdhfEqwF1JKoT2/location \ + -H "X-Api-Key: $api_key" +``` +{% /code %} + +{% code %} +```json +{ + "url": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743" +} +``` +{% /code %} + +{% /column %} +{% /row %} +{% /endpoint %}