Merge pull request #246 from autonomys/add-api-reference

feat(doc): create api documentation

Author: clostao

.yarn/install-state.gz

@@ -9,6 +9,7 @@
     "start:server": "node --loader ts-node/esm src/server.ts",
     "start": "node dist/server.js",
     "start:prod": "node dist/server.prod.js",
+    "start:docs": "node --loader ts-node/esm src/http/controllers/docs.ts",
     "test": "node --experimental-vm-modules ../node_modules/jest/bin/jest.js --runInBand --coverage",
     "lint": "eslint . "
   },
@@ -31,7 +32,7 @@
     "dotenv": "^16.4.5",
     "express": "^4.19.2",
     "jsonwebtoken": "^9.0.2",
-    "keyv": "^5.2.1",
+    "keyv": "^5.3.1",
     "lru-cache": "^11.0.2",
     "multer": "^1.4.5-lts.1",
     "multiformats": "^13.2.2",

backend/package.json

@@ -8,6 +8,7 @@ import { handleAuth } from './services/auth/express.js'
 import { uploadController } from './http/controllers/upload.js'
 import { config } from './config.js'
 import { logger } from './drivers/logger.js'
+import { docsController } from './http/controllers/docs.js'
 
 const createServer = async () => {
   const app = express()
@@ -34,6 +35,7 @@ const createServer = async () => {
   app.use('/objects', objectController)
   app.use('/subscriptions', subscriptionController)
   app.use('/uploads', uploadController)
+  app.use('/docs', docsController)
 
   app.get('/health', (_req, res) => {
     res.sendStatus(204)

backend/src/api.ts

@@ -0,0 +1,31 @@
+export const common = {
+  components: {
+    schemas: {
+      UploadOptions: {
+        type: 'object',
+        properties: {
+          compression: {
+            $ref: '#/components/schemas/CompressionOptions',
+          },
+          encryption: {
+            $ref: '#/components/schemas/EncryptionOptions',
+          },
+        },
+      },
+      CompressionOptions: {
+        type: 'object',
+        properties: {
+          algorithm: { type: 'string', enum: ['ZLIB'] },
+          level: { type: 'integer', default: 8 },
+        },
+      },
+      EncryptionOptions: {
+        type: 'object',
+        properties: {
+          algorithm: { type: 'string', enum: ['AES_256_GCM'] },
+          chunkSize: { type: 'integer', default: 1024 },
+        },
+      },
+    },
+  },
+}

backend/src/docs/reference/common.ts

@@ -0,0 +1,58 @@
+import { common } from './common.js'
+import { objects } from './objects.js'
+import { subscriptions } from './subscriptions.js'
+import { uploads } from './uploads.js'
+
+export const swagger = {
+  openapi: '3.0.0',
+  info: {
+    title: 'Auto Drive API',
+    version: '1.0.0',
+    description: 'API for Auto Drive',
+  },
+  servers: [
+    {
+      url: 'https://mainnet.auto-drive.autonomys.xyz/api',
+      description: 'Mainnet',
+    },
+    {
+      url: 'https://demo.auto-drive.autonomys.xyz/api',
+      description: 'Testnet',
+    },
+  ],
+  paths: {
+    ...subscriptions.paths,
+    ...uploads.paths,
+    ...objects.paths,
+  },
+  security: [
+    {
+      apiKey: [],
+      provider: [],
+    },
+  ],
+  components: {
+    schemas: {
+      ...uploads.components.schemas,
+      ...objects.components.schemas,
+      ...common.components.schemas,
+      ...subscriptions.components.schemas,
+    },
+    securitySchemes: {
+      apiKey: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'Authorization',
+        description:
+          'Bearer token for authentication. Example: Bearer <token>. Could be either an API key or a JWT token.',
+      },
+      provider: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'X-Auth-Provider',
+        description:
+          'Used for differentiating between different auth providers. For most use cases: X-Auth-Provider: apikey',
+      },
+    },
+  },
+}