chore: add v1 deprecated docs (#2423)

packages/api/v1/contract.ts

@@ -43,6 +43,9 @@ import {
 
 const c = initContract();
 
+const deprecatedDescription =
+  'This endpoint is deprecated, but will continue to be supported. For more details, see https://docs.documenso.com/developers/public-api.';
+
 export const ApiContractV1 = c.router(
   {
     getDocuments: {
@@ -55,6 +58,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get all documents',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     getDocument: {
@@ -66,6 +71,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get a single document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     downloadSignedDocument: {
@@ -78,6 +85,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Download a signed document when the storage transport is S3',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     createDocument: {
@@ -90,6 +99,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Upload a new document and get a presigned URL',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     createTemplate: {
@@ -102,6 +113,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a new template and get a presigned URL',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     deleteTemplate: {
@@ -114,6 +127,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a template',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     getTemplate: {
@@ -125,6 +140,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get a single template',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     getTemplates: {
@@ -137,6 +154,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get all templates',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     createDocumentFromTemplate: {
@@ -150,7 +169,7 @@ export const ApiContractV1 = c.router(
       },
       summary: 'Create a new document from an existing template',
       deprecated: true,
-      description: `This has been deprecated in favour of "/api/v1/templates/:templateId/generate-document". You may face unpredictable behavior using this endpoint as it is no longer maintained.`,
+      description: `${deprecatedDescription} \n\nIf you must use the V1 API, use "/api/v1/templates/:templateId/generate-document" instead.`,
     },
 
     generateDocumentFromTemplate: {
@@ -165,8 +184,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a new document from an existing template',
-      description:
-        'Create a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.',
+      deprecated: true,
+      description: `${deprecatedDescription} \n\nCreate a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.`,
     },
 
     sendDocument: {
@@ -181,9 +200,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Send a document for signing',
-      // I'm aware this should be in the variable itself, which it is, however it's difficult for users to find in our current UI.
-      description:
-        'Notes\n\n`sendEmail` - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true',
+      deprecated: true,
+      description: `${deprecatedDescription} \n\nNotes\n\nsendEmail - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true`,
     },
 
     resendDocument: {
@@ -198,6 +216,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Re-send a document for signing',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     deleteDocument: {
@@ -210,6 +230,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     createRecipient: {
@@ -224,6 +246,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a recipient for a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     updateRecipient: {
@@ -238,6 +262,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Update a recipient for a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     deleteRecipient: {
@@ -252,6 +278,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a recipient from a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     createField: {
@@ -266,6 +294,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a field for a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     updateField: {
@@ -280,6 +310,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Update a field for a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
 
     deleteField: {
@@ -294,6 +326,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a field from a document',
+      deprecated: true,
+      description: deprecatedDescription,
     },
   },
   {

packages/api/v1/openapi.ts

@@ -11,7 +11,8 @@ export const OpenAPIV1 = Object.assign(
       info: {
         title: 'Documenso API',
         version: '1.0.0',
-        description: 'The Documenso API for retrieving, creating, updating and deleting documents.',
+        description:
+          'API V1 is deprecated, but will continue to be supported. For more details, see https://docs.documenso.com/developers/public-api. \n\nThe Documenso API for retrieving, creating, updating and deleting documents.',
       },
       servers: [
         {