Skip to content

Update the OpenAPI specifications to define query parameters with their correct intended types #1018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
youngjungithub wants to merge 2 commits into from
Closed

Update the OpenAPI specifications to define query parameters with their correct intended types #1018

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba6977e
Fix integer type representation in OpenAPI schema generation
youngjungithub Mar 5, 2025
484690a
fix: represent integer query parameters with correct type
youngjungithub Mar 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/openapi-generator/src/jsdoc.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ export function parseCommentBlock(comment: Block): JSDoc {
if (line.tokens.description === '') {
continue;
}
summary = line.tokens.description;
summary = line.tokens.description.trim();
} else {
description = `${description ?? ''}\n${line.tokens.description}`;
}
Expand Down
1 change: 1 addition & 0 deletions packages/openapi-generator/src/knownImports.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ export const KNOWN_IMPORTS: KnownImports = {
'io-ts': {
string: () => E.right({ type: 'string', primitive: true }),
number: () => E.right({ type: 'number', primitive: true }),
integer: () => E.right({ type: 'integer', primitive: true }),
bigint: () => E.right({ type: 'number' }),
boolean: () => E.right({ type: 'boolean', primitive: true }),
null: () => E.right({ type: 'null' }),
Expand Down
9 changes: 7 additions & 2 deletions packages/openapi-generator/src/openapi.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,23 @@ export function schemaToOpenAPI(
switch (schema.type) {
case 'boolean':
case 'string':
case 'number':
return {
type: schema.type,
...(schema.enum ? { enum: schema.enum } : {}),
...defaultOpenAPIObject,
};
case 'integer':
case 'number':
return {
type: 'number',
...(schema.enum ? { enum: schema.enum } : {}),
...defaultOpenAPIObject,
};
case 'integer':
return {
type: 'integer',
...(schema.enum ? { enum: schema.enum } : {}),
...defaultOpenAPIObject,
};
case 'null':
// TODO: OpenAPI v3 does not have an explicit null type, is there a better way to represent this?
// Or should we just conflate explicit null and undefined properties?
Expand Down
122 changes: 122 additions & 0 deletions packages/openapi-generator/test/openapi/base.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -716,6 +716,128 @@ testCase('route with array union of null and undefined', ROUTE_WITH_ARRAY_UNION_
}
});

const ROUTE_WITH_INTEGER_QUERY_PARAM = `
import * as t from 'io-ts';
import * as h from '@api-ts/io-ts-http';

/**
* A route with integer query parameter
*
* @operationId api.v1.integerTest
* @tag Test Routes
*/
export const route = h.httpRoute({
path: '/items',
method: 'GET',
request: h.httpRequest({
query: {
/**
* Maximum number of items to return
* @example 100
*/
limit: t.integer,

/**
* Page number for pagination
* @minimum 1
*/
page: t.integer,

/**
* Regular number parameter for comparison
*/
ratio: t.number
},
}),
response: {
200: t.type({
items: t.array(t.string),
totalCount: t.integer
})
},
});
`;

testCase('route with integer query parameters', ROUTE_WITH_INTEGER_QUERY_PARAM, {
openapi: '3.0.3',
info: {
title: 'Test',
version: '1.0.0',
},
paths: {
'/items': {
get: {
summary: 'A route with integer query parameter',
operationId: 'api.v1.integerTest',
tags: [
'Test Routes'
],
parameters: [
{
name: 'limit',
description: 'Maximum number of items to return',
in: 'query',
required: true,
schema: {
type: 'integer',
example: 100
}
},
{
name: 'page',
description: 'Page number for pagination',
in: 'query',
required: true,
schema: {
type: 'integer',
minimum: 1
}
},
{
name: 'ratio',
description: 'Regular number parameter for comparison',
in: 'query',
required: true,
schema: {
type: 'number'
}
}
],
responses: {
'200': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
items: {
type: 'array',
items: {
type: 'string'
}
},
totalCount: {
type: 'integer'
}
},
required: [
'items',
'totalCount'
]
}
}
}
}
}
}
}
},
components: {
schemas: {}
}
});

const MULTIPLE_ROUTES = `
import * as t from 'io-ts';
import * as h from '@api-ts/io-ts-http';
Expand Down