propagate suggestions

openapi.yaml

@@ -1,4 +1,5 @@
 openapi: 3.1.0
+
 info:
   version: 0.1.0
   title: AsyncAPI Server API
@@ -15,7 +16,7 @@ servers:
   - url: https://api.asyncapi.io/v1
 
 paths:
-  /generate/template:
+  /generate:
     post:
       summary: Generate the given AsyncAPI template.
       operationId: generateTemplate
@@ -44,19 +45,19 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: '#/components/schemas/Problem'
         '422':
           description: Failed to generate the given template due to invalid parameters.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: '#/components/schemas/Problem'
         default:
-          description: Unexpected error.
+          description: Unexpected problem.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: '#/components/schemas/Problem'
 
 components:
   schemas:
@@ -85,20 +86,47 @@ components:
         parameters:
           type: object
           description: |
-            Template parameters to be generated. Each template has different parameters that you should check in the documentation, which is usually located in the template's repository.
+            Template parameters to be generated. Each template has different parameters that you should check in the documentation, 
+            which is usually located in the template's repository.
             This field is optional but may be required for some templates.
           minProperties: 1
           additionalProperties: true
-    Error:
+    Problem:
       type: object
-      required:
-        - code
-        - message
       properties:
-        code:
+        type:
+          type: string
+          format: uri
+          description: |
+            An absolute URI that identifies the problem type. When dereferenced,
+            it SHOULD provide human-readable documentation for the problem type
+            (e.g., using HTML).
+          default: 'about:blank'
+          example: 'https://api.asyncapi.io/problem/invalid-template-parameters'
+        title:
+          type: string
+          description: |
+            A short, summary of the problem type. Written in english and readable.
+          example: Invalid AsyncAPI document.
+        status:
           type: integer
           format: int32
-        message:
+          description: |
+            The HTTP status code generated by the origin server for this occurrence
+            of the problem.
+          minimum: 100
+          maximum: 600
+          exclusiveMaximum: true
+          example: 422
+        detail:
           type: string
-        errors:
-          type: array
+          description: |
+            A human readable explanation specific to this occurrence of the problem.
+          example: Connection to database timed out
+        instance:
+          type: string
+          format: uri
+          description: |
+            An absolute URI that identifies the specific occurrence of the problem.
+            It may or may not yield further information if dereferenced.
+      additionalProperties: true