From 8165c69727850a900c48240f20d758e6f84167cd 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 | 43 +++++++++++- 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 | 66 +++++++++++++++++++ 8 files changed, 157 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..c523c7f6d 100644 --- a/markdoc.config.mjs +++ b/markdoc.config.mjs @@ -1,6 +1,31 @@ import { defineMarkdocConfig, component } from '@astrojs/markdoc/config'; +import shiki from '@astrojs/markdoc/shiki'; export default defineMarkdocConfig({ + extends: [ + shiki({ + // Choose from Shiki's built-in themes (or add your own) + // Default: 'github-dark' + // https://github.com/shikijs/shiki/blob/main/docs/themes.md + theme: 'github-light', + // Enable word wrap to prevent horizontal scrolling + // Default: false + wrap: true, + // Pass custom languages + // Note: Shiki has countless langs built-in, including `.astro`! + // https://github.com/shikijs/shiki/blob/main/docs/languages.md + langs: [], + }), + ], + nodes: { + fence: { + render: component('./src/components/Code.astro'), + attributes: { + language: { type: String }, + content: { type: String }, + }, + }, + }, tags: { properties: { render: component('./src/components/Properties.astro'), @@ -11,6 +36,22 @@ 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 }, + }, + }, } }); 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..72103d582 100644 --- a/src/__tests__/__snapshots__/links.integration.test.js.snap +++ b/src/__tests__/__snapshots__/links.integration.test.js.snap @@ -311,6 +311,7 @@ exports[`the build should not break any links 1`] = ` "/api/media-uploads#models", "/api/media-uploads#operations", "/api/media-uploads#properties", + "/api/media-uploads#required-fields", "/api/media-uploads#top", "/api/merchant-configs", "/api/merchant-configs#contents", 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..d7fbbca08 100644 --- a/src/content/api/media-uploads.mdoc +++ b/src/content/api/media-uploads.mdoc @@ -44,3 +44,69 @@ 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 %} +### Required Fields +{% 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 %} + +```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" + }' +``` + +```json +{ + "id": "DKTs3U38hdhfEqwF1JKoT2", + "uploadUrl": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743" +} +``` + +{% /column %} +{% /row %} +{% /endpoint %} + + +{% endpoint method="GET" path="/api/media-uploads/{mediaUploadId}/location" %} +## Get Media Upload Location EXPERIMENTAL +{% row %} +{% column/ %} +{% column sticky=true %} + +```bash +curl https://service.centrapay.com/api/media-uploads/DKTs3U38hdhfEqwF1JKoT2/location \ + -H "X-Api-Key: $api_key" +``` + +```json +{ + "url": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743" +} +``` + +{% /column %} +{% /row %} +{% /endpoint %}