diff --git a/README.md b/README.md index 39831f4..63bf369 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,9 @@ interface MyResult { } const bodyCodec = t.type({ - /** Descriptions are also supported in io-ts codecs */ + /** Descriptions are also supported in io-ts codecs + * @example Lets you set an example value for a particular property + */ name: t.string }) diff --git a/src/generate.ts b/src/generate.ts index 2a8e0b3..43b089b 100644 --- a/src/generate.ts +++ b/src/generate.ts @@ -789,13 +789,14 @@ const typeToRequestParameters = ( } return props.map((prop): OpenAPIV3.ParameterObject => { const description = getDescriptionFromComment(ctx, prop) + const example = getExampleValue(prop) return { name: prop.name, in: in_, required: in_ === 'path' ? true : !isOptional(prop), schema: { type: 'string', - example: getExampleValue(prop), + ...(example ? { example } : undefined), }, ...(descriptions ? descriptions.get(prop.name) @@ -836,7 +837,7 @@ const getBaseSchema = ( symbol: ts.Symbol | undefined ): BaseSchema => { const description = symbol ? getDescriptionFromComment(ctx, symbol) : '' - const example = symbol ? getExampleValue(symbol) : '' + const example = symbol ? getExampleValue(symbol) : undefined return { ...(description ? { description } : undefined), ...(example ? { example } : undefined), diff --git a/tests/__snapshots__/generate.spec.ts.snap b/tests/__snapshots__/generate.spec.ts.snap index d599bb2..644a026 100644 --- a/tests/__snapshots__/generate.spec.ts.snap +++ b/tests/__snapshots__/generate.spec.ts.snap @@ -994,6 +994,89 @@ Object { }, }, }, + "/route-with-example-values": Object { + "get": Object { + "operationId": "routeWithExampleValues", + "parameters": Array [ + Object { + "in": "query", + "name": "queryParam", + "required": true, + "schema": Object { + "example": "Example query", + "type": "string", + }, + }, + Object { + "in": "header", + "name": "headerValue", + "required": true, + "schema": Object { + "example": "Example header", + "type": "string", + }, + }, + Object { + "in": "cookie", + "name": "cookieValue", + "required": true, + "schema": Object { + "example": "Example cookie", + "type": "string", + }, + }, + ], + "requestBody": Object { + "content": Object { + "application/json": Object { + "schema": Object { + "properties": Object { + "requestParam": Object { + "example": "Example request parameter", + "type": "string", + }, + }, + "required": Array [ + "requestParam", + ], + "type": "object", + }, + }, + }, + }, + "responses": Object { + "200": Object { + "content": Object { + "application/json": Object { + "schema": Object { + "properties": Object { + "responseParam": Object { + "example": "Example response parameter", + "type": "string", + }, + }, + "required": Array [ + "responseParam", + ], + "type": "object", + }, + }, + }, + "description": "OK", + }, + "400": Object { + "content": Object { + "text/plain": Object { + "schema": Object { + "type": "string", + }, + }, + }, + "description": "Bad Request", + }, + }, + }, + }, "/same-path-route": Object { "get": Object { "operationId": "samePathRoute1", diff --git a/tests/test-routes.ts b/tests/test-routes.ts index 8962c7a..d222d4a 100644 --- a/tests/test-routes.ts +++ b/tests/test-routes.ts @@ -363,6 +363,44 @@ const customContentType: Route< return Response.ok('foo;bar;baz', { 'Content-Type': 'text/csv' }) }) +const queryWithExampleValue = t.type({ + /** @example Example query */ + queryParam: t.string, +}) + +const headerWithExampleValue = t.type({ + /** @example Example header */ + headerValue: t.string, +}) + +const cookieWithExampleValue = t.type({ + /** @example Example cookie */ + cookieValue: t.string, +}) + +const requestBodyWithExampleValue = t.type({ + /** @example Example request parameter */ + requestParam: t.string, +}) + +const responseBodyWithExampleValue = t.type({ + /** @example Example response parameter */ + responseParam: t.string, +}) + +const routeWithExampleValues: Route< + | Response.Ok> + | Response.BadRequest +> = route + .get('/route-with-example-values') + .use( + Parser.body(requestBodyWithExampleValue), + Parser.query(queryWithExampleValue), + Parser.headers(headerWithExampleValue), + Parser.cookies(cookieWithExampleValue) + ) + .handler(async () => Response.ok({ responseParam: 'foo' })) + export default router( constant, anyOf, @@ -382,6 +420,7 @@ export default router( responseHeaders, usesCustomRoute, schemaDocstrings, + routeWithExampleValues, binaryResponse, samePathRoute1, samePathRoute2,