From f0ef1e33cd8b6e5fcfe80a0c3cf35b8a5276946e Mon Sep 17 00:00:00 2001
From: Copple <10214025+kiwicopple@users.noreply.github.com>
Date: Wed, 3 Aug 2022 21:51:50 +0200
Subject: [PATCH] cleaning up the api spec
---
apps/reference/_storage/usage.mdx | 486 +++++++++++++++++-
apps/reference/docusaurus.config.js | 83 ++-
apps/reference/nav/_referenceNavbar.js | 3 +-
packages/spec/src/docs/api.ts | 15 +-
.../spec/src/docs/templates/ApiTemplate.ts | 22 +
5 files changed, 561 insertions(+), 48 deletions(-)
diff --git a/apps/reference/_storage/usage.mdx b/apps/reference/_storage/usage.mdx
index a686b95168a..a438b572594 100644
--- a/apps/reference/_storage/usage.mdx
+++ b/apps/reference/_storage/usage.mdx
@@ -1,8 +1,13 @@
---
id: usage
title: Usage
+toc_max_heading_level: 2
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
API documentation for Supabase Storage
@@ -14,176 +19,619 @@ API documentation for Supabase Storage
-### Create a bucket
+
+## Create a bucket {#create-a-bucket}
```
/bucket/
```
+### Responses
-### Gets all buckets
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Gets all buckets {#gets-all-buckets}
```
/bucket/
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Empty a bucket
+
+
+## Empty a bucket {#empty-a-bucket}
```
/bucket/{bucketId}/empty
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Get details of a bucket
+
+
+## Get details of a bucket {#get-details-of-a-bucket}
```
/bucket/{bucketId}
```
+### Responses
-### Update properties of a bucket
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Update properties of a bucket {#update-properties-of-a-bucket}
```
/bucket/{bucketId}
```
+### Responses
-### Delete a bucket
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Delete a bucket {#delete-a-bucket}
```
/bucket/{bucketId}
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Delete an object
+
+
+## Delete an object {#delete-an-object}
```
/object/{bucketName}/{wildcard}
```
+### Responses
-### Deprecated (use GET /object/authenticated/{bucketName} instead): Retrieve an object
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Deprecated (use GET /object/authenticated/{bucketName} instead): Retrieve an object {#deprecated-use-get-objectauthenticatedbucketname-instead-retrieve-an-object}
```
/object/{bucketName}/{wildcard}
```
+### Responses
-### Update the object at an existing key
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Update the object at an existing key {#update-the-object-at-an-existing-key}
```
/object/{bucketName}/{wildcard}
```
+### Responses
-### Upload a new object
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Upload a new object {#upload-a-new-object}
```
/object/{bucketName}/{wildcard}
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Delete multiple objects
+
+
+## Delete multiple objects {#delete-multiple-objects}
```
/object/{bucketName}
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Retrieve an object
+
+
+## Retrieve an object {#retrieve-an-object}
```
/object/authenticated/{bucketName}/{wildcard}
```
+### Responses
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Generate a presigned url to retrieve an object
+
+
+## Generate a presigned url to retrieve an object {#generate-a-presigned-url-to-retrieve-an-object}
```
/object/sign/{bucketName}/{wildcard}
```
+### Responses
-### Retrieve an object via a presigned URL
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
+
+
+## Retrieve an object via a presigned URL {#retrieve-an-object-via-a-presigned-url}
```
/object/sign/{bucketName}/{wildcard}
```
+### Responses
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Generate presigned urls to retrieve objects
+
+
+## Generate presigned urls to retrieve objects {#generate-presigned-urls-to-retrieve-objects}
```
/object/sign/{bucketName}
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Moves an object
+
+
+## Moves an object {#moves-an-object}
```
/object/move
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Search for objects under a prefix
+
+
+## Search for objects under a prefix {#search-for-objects-under-a-prefix}
```
/object/list/{bucketName}
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Copies an object
+
+
+## Copies an object {#copies-an-object}
```
/object/copy
```
+### Responses
+
+
+
+
+
+```
+200
+```
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
-### Retrieve an object from a public bucket
+
+
+## Retrieve an object from a public bucket {#retrieve-an-object-from-a-public-bucket}
```
/object/public/{bucketName}/{wildcard}
```
+### Responses
+
+
+
+
+
+```
+400
+```
+
+
+
+
+
+
+
diff --git a/apps/reference/docusaurus.config.js b/apps/reference/docusaurus.config.js
index 59bb7899679..91b9b1fe5c6 100644
--- a/apps/reference/docusaurus.config.js
+++ b/apps/reference/docusaurus.config.js
@@ -123,11 +123,48 @@ const config = {
footer: {
links: [
{
- title: 'Reference',
+ title: 'Company',
items: [
{
- label: 'Supabase CLI',
- to: '/cli',
+ label: 'Blog',
+ to: 'https://supabase.com/blog',
+ },
+ {
+ label: 'Open source',
+ to: '/oss',
+ },
+ {
+ label: 'Humans.txt',
+ to: 'https://supabase.com/humans.txt',
+ },
+ {
+ label: 'Lawyers.txt',
+ to: 'https://supabase.com/lawyers.txt',
+ },
+ ],
+ },
+ {
+ title: 'Resources',
+ items: [
+ {
+ label: 'Brand Assets',
+ to: 'https://supabase.com/brand-assets',
+ },
+ {
+ label: 'Docs',
+ to: 'https://supabase.com/docs',
+ },
+ {
+ label: 'Pricing',
+ to: 'https://supabase.com/pricing',
+ },
+ {
+ label: 'Support',
+ to: '/support',
+ },
+ {
+ label: 'System Status',
+ to: 'https://status.supabase.com/',
},
],
},
@@ -135,42 +172,38 @@ const config = {
title: 'Community',
items: [
{
- label: 'Stack Overflow',
- href: 'https://stackoverflow.com/questions/tagged/supabase',
- },
- {
- label: 'Discord',
- href: 'https://discord.supabase.com',
+ label: 'GitHub',
+ href: 'https://github.com/supabase/supabase',
},
{
label: 'Twitter',
href: 'https://twitter.com/supabase',
},
+ {
+ label: 'DevTo',
+ href: 'https://dev.to/supabase',
+ },
+ {
+ label: 'RSS',
+ href: 'https://supabase.com/rss.xml',
+ },
+ {
+ label: 'Discord',
+ href: 'https://discord.supabase.com',
+ },
],
},
{
- title: 'More',
+ title: 'Beta',
items: [
{
- label: 'Supabase Website',
- href: 'https://supabase.com',
- },
- {
- label: 'Supabase Docs',
- href: 'https://supabase.com/docs',
- },
- {
- label: 'Supabase GitHub',
- href: 'https://github.com/supabase/supabase',
- },
- {
- label: 'Supabase Community GitHub',
- href: 'https://github.com/supabase-community/supabase',
+ label: 'Join our beta',
+ href: 'https://app.supabase.com',
},
],
},
],
- copyright: `Copyright © ${new Date().getFullYear()} Supabase, Inc.`,
+ copyright: `Copyright © ${new Date().getFullYear()} Supabase.`,
},
prism: {
additionalLanguages: ['dart'],
diff --git a/apps/reference/nav/_referenceNavbar.js b/apps/reference/nav/_referenceNavbar.js
index 52524e109e2..ef5fa8788ec 100644
--- a/apps/reference/nav/_referenceNavbar.js
+++ b/apps/reference/nav/_referenceNavbar.js
@@ -5,9 +5,10 @@ const navbar = [
position: 'left',
},
{
- href: 'https://supabase.com/docs/guides',
+ href: '/',
label: 'Reference',
position: 'left',
+ // activeLinkRegex: '',
},
{ href: 'https://app.supabase.com', label: 'Login', position: 'right' },
diff --git a/packages/spec/src/docs/api.ts b/packages/spec/src/docs/api.ts
index 70557093d58..85041e38edd 100644
--- a/packages/spec/src/docs/api.ts
+++ b/packages/spec/src/docs/api.ts
@@ -1,5 +1,5 @@
import template from './templates/ApiTemplate'
-import { toArrayWithKey } from './helpers'
+import { slugify, toArrayWithKey } from './helpers'
import { OpenAPIV3, OpenAPIV2 } from 'openapi-types'
const fs = require('fs')
const ejs = require('ejs')
@@ -51,10 +51,19 @@ async function gen_v3(spec: OpenAPIV3.Document, dest: string) {
// OPENAPI-SPEC-VERSION: 2.0
async function gen_v2(spec: OpenAPIV2.Document, dest: string) {
- const paths = Object.entries(spec.paths).map(([key, path], i) => {
+ const paths = Object.entries(spec.paths).map(([key, path]) => {
return {
path: key,
- operations: toArrayWithKey(path!, 'operation'),
+ operations: toArrayWithKey(path!, 'operation').map((o) => {
+ const operation = o as OpenAPIV2.OperationObject & {
+ path: string
+ }
+ return {
+ ...operation,
+ operationId: slugify(operation.summary!),
+ responses: toArrayWithKey(operation.responses!, 'responseCode'),
+ }
+ }),
}
})
diff --git a/packages/spec/src/docs/templates/ApiTemplate.ts b/packages/spec/src/docs/templates/ApiTemplate.ts
index cca56ac3f2f..126c0b7897d 100644
--- a/packages/spec/src/docs/templates/ApiTemplate.ts
+++ b/packages/spec/src/docs/templates/ApiTemplate.ts
@@ -2,8 +2,13 @@ const template = `
---
id: usage
title: Usage
+toc_max_heading_level: 2
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
<%- info.description %>
@@ -15,12 +20,29 @@ title: Usage
<% paths.forEach(function(path){ %>
<% path.operations.forEach(function(operation){ %>
+
## <%- operation.summary %> {#<%- operation.operationId %>}
\`\`\`
<%- path.path %>
\`\`\`
+
+### Responses
+
+
+<% operation.responses.forEach(function(response){ %>
+
+
+\`\`\`
+<%- response.responseCode %>
+\`\`\`
+
+
+<% }); %>
+
+
+
<% }); %>
<% }); %>