api: add schema descriptions and examples

apps/api/src/index.ts

@@ -17,7 +17,6 @@ import { withErrorHandler } from "./middleware/error";
 import { withProject } from "./middleware/project";
 import { withSwagger } from "./middleware/swagger";
 import { authRoutes } from "./routes/auth";
-import { contractsRoutes } from "./routes/contracts";
 import { harvestersRoutes } from "./routes/harvesters";
 import { projectsRoutes } from "./routes/projects";
 import { transactionsRoutes } from "./routes/transactions";
@@ -87,7 +86,6 @@ const main = async () => {
     app.register(authRoutes(ctx)),
     app.register(usersRoutes(ctx)),
     app.register(projectsRoutes(ctx)),
-    app.register(contractsRoutes(ctx)),
     app.register(transactionsRoutes(ctx)),
     app.register(harvestersRoutes(ctx)),
   ]);

apps/api/src/middleware/swagger.ts

@@ -14,6 +14,16 @@ export const withSwagger = async (app: FastifyInstance) => {
           "Backend APIs for the Treasure Development Kit powering the Treasure Web3 gaming ecosystem",
         version: "1.0.0",
       },
+      components: {
+        securitySchemes: {
+          authToken: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT",
+            description: "Authentication token obtained by calling POST /login",
+          },
+        },
+      },
     },
     swagger: {
       consumes: ["application/json"],
@@ -28,8 +38,6 @@ export const withSwagger = async (app: FastifyInstance) => {
         nextSchema.tags = ["harvesters"];
       } else if (url.startsWith("/projects")) {
         nextSchema.tags = ["projects"];
-      } else if (url.startsWith("/contracts")) {
-        nextSchema.tags = ["contracts"];
       } else if (url.startsWith("/transactions")) {
         nextSchema.tags = ["transactions"];
       } else if (url.startsWith("/users")) {

apps/api/src/routes/auth.ts

@@ -3,6 +3,7 @@ import { DEFAULT_TDK_CHAIN_ID, decodeAuthToken } from "@treasure-dev/tdk-core";
 import type { FastifyPluginAsync } from "fastify";
 
 import "../middleware/project";
+import "../middleware/swagger";
 import type {
   LoginBody,
   LoginReply,
@@ -38,6 +39,8 @@ export const authRoutes =
       "/login/payload",
       {
         schema: {
+          summary: "Generate login payload",
+          description: "Generate a login payload for a given wallet address",
           querystring: readLoginPayloadQuerystringSchema,
           response: {
             200: readLoginPayloadReplySchema,
@@ -56,6 +59,8 @@ export const authRoutes =
         "/login",
         {
           schema: {
+            summary: "Log in",
+            description: "Log in with a signed payload",
             body: loginBodySchema,
             response: {
               200: loginReplySchema,
@@ -151,6 +156,9 @@ export const authRoutes =
         "/auth/authenticate",
         {
           schema: {
+            summary: "Log in via third party",
+            description:
+              "Start login session with custom authentication method",
             body: authenticateBodySchema,
             response: {
               200: authenticateReplySchema,
@@ -188,6 +196,9 @@ export const authRoutes =
       "/auth/verify",
       {
         schema: {
+          summary: "Verify third-party login",
+          description:
+            "Verify login session started via custom authentication method",
           body: authVerifyBodySchema,
           response: {
             200: authVerifyReplySchema,

apps/api/src/routes/harvesters.ts

@@ -8,6 +8,7 @@ import type { FastifyPluginAsync } from "fastify";
 import { zeroAddress } from "viem";
 
 import "../middleware/chain";
+import "../middleware/swagger";
 import type {
   ReadHarvesterCorruptionRemovalParams,
   ReadHarvesterCorruptionRemovalReply,
@@ -32,6 +33,9 @@ export const harvestersRoutes =
       "/harvesters/:id",
       {
         schema: {
+          summary: "Get Harvester details",
+          description:
+            "Get Harvester details including user info if valid authorization token is provided",
           response: {
             200: readHarvesterReplySchema,
           },
@@ -85,6 +89,9 @@ export const harvestersRoutes =
       "/harvesters/:id/corruption-removal",
       {
         schema: {
+          summary: "Get Harvester Corruption Removal",
+          description:
+            "Get Corruption Removal recipes for Harvester including user info if valid authorization token is provided",
           response: {
             200: readHarvesterCorruptionRemovalReplySchema,
           },

apps/api/src/routes/projects.ts

@@ -1,6 +1,7 @@
 import type { FastifyPluginAsync } from "fastify";
 
 import "../middleware/chain";
+import "../middleware/swagger";
 import {
   type ReadProjectParams,
   type ReadProjectReply,
@@ -18,6 +19,8 @@ export const projectsRoutes =
       "/projects/:slug",
       {
         schema: {
+          summary: "Get project details",
+          description: "Get project details to power login experience",
           response: {
             200: readProjectReplySchema,
           },

apps/api/src/routes/transactions.ts

@@ -2,6 +2,7 @@ import type { FastifyPluginAsync } from "fastify";
 
 import "../middleware/chain";
 import "../middleware/project";
+import "../middleware/swagger";
 import {
   type CreateTransactionBody,
   type CreateTransactionReply,
@@ -25,6 +26,9 @@ export const transactionsRoutes =
       "/transactions",
       {
         schema: {
+          summary: "Write contract",
+          description: "Call a contract write function",
+          security: [{ authToken: [] }],
           body: createTransactionBodySchema,
           response: {
             200: createTransactionReplySchema,
@@ -71,6 +75,8 @@ export const transactionsRoutes =
       "/transactions/:queueId",
       {
         schema: {
+          summary: "Get transaction",
+          description: "Get transaction status by queue ID",
           response: {
             200: readTransactionReplySchema,
           },

apps/api/src/routes/users.ts

@@ -2,6 +2,7 @@ import { getAllActiveSigners } from "@treasure-dev/tdk-core";
 import type { FastifyPluginAsync } from "fastify";
 
 import "../middleware/chain";
+import "../middleware/swagger";
 import {
   type ErrorReply,
   type ReadCurrentUserReply,
@@ -19,6 +20,9 @@ export const usersRoutes =
       "/users/me",
       {
         schema: {
+          summary: "Get current user",
+          description: "Get current user profile details and on-chain sessions",
+          security: [{ authToken: [] }],
           response: {
             200: readCurrentUserReplySchema,
           },