diff --git a/README.md b/README.md index 90d1ff3b..c88ec8f7 100644 --- 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.BadRequest> = - 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 index 50be129a..675d6665 100644 --- a/tests/__snapshots__/generate.spec.ts.snap +++ b/tests/__snapshots__/generate.spec.ts.snap @@ -360,19 +360,37 @@ 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", }, @@ -380,6 +398,16 @@ Array [ }, "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 index 5a8abd9a..457d0935 100644 --- a/tests/test-routes.ts +++ b/tests/test-routes.ts @@ -158,15 +158,23 @@ const usesCustomRoute: Route> = 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> = route +const schemaDocstrings: Route< + Response.Ok | Response.BadRequest +> = 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(