Document how descriptions work with io-ts codecs

akheron · Feb 1, 2021 · 5a9d8d0 · 5a9d8d0
1 parent 9f024c9
commit 5a9d8d0
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -21,8 +21,18 @@ JSDoc comments serve as additional documentation:
 
 import { Response, Route, route, router } from 'typera-express'
 
+interface MyResult {
+  /** The JSDoc text is used as a description for object fields */
+  field: number
+}
+
+const bodyCodec = t.type({
+  /** Descriptions are also supported in io-ts codecs */
+  name: t.string
+})
+
 /**
- * The JSDoc text is used as a description for the route (optional).
+ * Routes can also have a description. Note that descriptions are entirely optional.
  *
  * @summary You can also set a short summary
  * @tags Tag1, Tag2
@@ -32,12 +42,7 @@ import { Response, Route, route, router } from 'typera-express'
  * spans multile lines.
  */
 const myRoute: Route<Response.Ok<MyResult> | Response.BadRequest<string>> =
-  route.get(...).handler(...)
-
-interface MyResult {
-  /** Object properties can have descriptions, too */
-  field: number
-}
+  route.post(...).use(Parser.body(bodyCodec)).handler(...)
 
 // ...
 

diff --git a/tests/__snapshots__/generate.spec.ts.snap b/tests/__snapshots__/generate.spec.ts.snap
@@ -360,26 +360,54 @@ Array [
       },
       "/schema-docstrings": Object {
         "get": Object {
+          "requestBody": Object {
+            "content": Object {
+              "application/json": Object {
+                "schema": Object {
+                  "properties": Object {
+                    "inputField": Object {
+                      "description": "Input field description",
+                      "type": "number",
+                    },
+                  },
+                  "required": Array [
+                    "inputField",
+                  ],
+                  "type": "object",
+                },
+              },
+            },
+          },
           "responses": Object {
             "200": Object {
               "content": Object {
                 "application/json": Object {
                   "schema": Object {
                     "properties": Object {
-                      "field": Object {
-                        "description": "Field documentation here",
-                        "type": "number",
+                      "outputField": Object {
+                        "description": "OUtput field description here",
+                        "type": "string",
                       },
                     },
                     "required": Array [
-                      "field",
+                      "outputField",
                     ],
                     "type": "object",
                   },
                 },
               },
               "description": "200",
             },
+            "400": Object {
+              "content": Object {
+                "text/plain": Object {
+                  "schema": Object {
+                    "type": "string",
+                  },
+                },
+              },
+              "description": "400",
+            },
           },
         },
       },

diff --git a/tests/test-routes.ts b/tests/test-routes.ts
@@ -158,15 +158,23 @@ const usesCustomRoute: Route<Response.Ok<string>> = customRoute()
   })
 
 // Docstrings in input/output schemas
+const documentedCodec = t.type({
+  /** Input field description */
+  inputField: t.number,
+})
+
 interface DocumentedInterface {
-  /** Field documentation here */
-  field: number
+  /** OUtput field description here */
+  outputField: string
 }
 
-const schemaDocstrings: Route<Response.Ok<DocumentedInterface>> = route
+const schemaDocstrings: Route<
+  Response.Ok<DocumentedInterface> | Response.BadRequest<string>
+> = route
   .get('/schema-docstrings')
-  .handler(async () => {
-    return Response.ok({ field: 42 })
+  .use(Parser.body(documentedCodec))
+  .handler(async (request) => {
+    return Response.ok({ outputField: request.body.inputField + '' })
   })
 
 export default router(